Updating JSON Schema

[tsurdilo]

Signed-off-by: tsurdilo tsurdilo@redhat.com

Updating specification JSON Schema:

• Added description of each property
• Added examples
• Added restrictions (like minLength) where it was missing (and is required per spec)

Renamed spec.json to spec-schema.json so its more clear what the file contains.

Reason for change is

• Be more readable for users
• Allow tooling like json validators / linters etc to show descriptions, example values etc to have better user experience, for example here are some screenshots with the schema update in this pr and json validator support in VSCode:

[duglin]

Dunno if this is useful or not, but here's a diff from the old schema file:

$ diff -w spec.json.sav spec-schema.json 
2,17c2,4
<   "$ref": "#/definitions/event",
<   "definitions": {
<     "specversion": {
<       "type": "string",
<       "minLength": 1
<     },
<     "datacontenttype": {
<       "type": "string"
<     },
<     "data": {
<       "type": ["object", "string"]
<     },
<     "data_base64": {
<       "type": "string"
<     },
<     "event": {
---
>   "$schema": "http://json-schema.org/schema#",
>   "description": "CloudEvents Specification JSON Schema",
>   "type": "object",
19,23c6,11
<         "specversion": {
<           "$ref": "#/definitions/specversion"
<         },
<         "datacontenttype": {
<           "$ref": "#/definitions/datacontenttype"
---
>     "id": {
>       "description": "Identifies the event.",
>       "$ref": "#/definitions/iddef",
>       "examples": [
>         "A234-1234-1234"
>       ]
25,26c13,23
<         "data": {
<           "$ref": "#/definitions/data"
---
>     "source": {
>       "description": "Identifies the context in which an event happened.",
>       "$ref": "#/definitions/sourcedef",
>       "examples" : [
>         "https://github.com/cloudevents",
>         "mailto:cncf-wg-serverless@lists.cncf.io",
>         "urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66",
>         "cloudevents/spec/pull/123",
>         "/sensors/tn-1234567/alerts",
>         "1-555-123-4567"
>       ]
28,29c25,30
<         "data_base64": {
<           "$ref": "#/definitions/data_base64"
---
>     "specversion": {
>       "description": "The version of the CloudEvents specification which the event uses.",
>       "$ref": "#/definitions/specversiondef",
>       "examples": [
>         "1.0"
>       ]
31,32c32,38
<         "id": {
<           "$ref": "#/definitions/id"
---
>     "type": {
>       "description": "Describes the type of event related to the originating occurrence.",
>       "$ref": "#/definitions/typedef",
>       "examples" : [
>         "com.github.pull.create",
>         "com.example.object.delete.v2"
>       ]
34,35c40,48
<         "time": {
<           "$ref": "#/definitions/time"
---
>     "datacontenttype": {
>       "description": "Content type of the data value. Must adhere to RFC 2046 format.",
>       "$ref": "#/definitions/datacontenttypedef",
>       "examples": [
>         "text/xml",
>         "application/json",
>         "image/png",
>         "multipart/form-data"
>       ]
38c51,52
<           "$ref": "#/definitions/dataschema"
---
>       "description": "Identifies the schema that data adheres to.",
>       "$ref": "#/definitions/dataschemadef"
41c55,59
<           "$ref": "#/definitions/subject"
---
>       "description": "Describes the subject of the event in the context of the event producer (identified by source).",
>       "$ref": "#/definitions/subjectdef",
>       "examples": [
>         "mynewfile.jpg"
>       ]
43,44c61,66
<         "type": {
<           "$ref": "#/definitions/type"
---
>     "time": {
>       "description": "Timestamp of when the occurrence happened. Must adhere to RFC 3339.",
>       "$ref": "#/definitions/timedef",
>       "examples": [
>         "2018-04-05T17:31:00Z"
>       ]
46,47c68,80
<         "source": {
<           "$ref": "#/definitions/source"
---
>     "data": {
>       "description": "The event payload.",
>       "$ref": "#/definitions/datadef",
>       "examples": [
>         "<much wow=\"xml\"/>"
>       ]
>     },
>     "data_base64": {
>       "description": "Base64 encoded event payload. Must adhere to RFC4648.",
>       "$ref": "#/definitions/data_base64def",
>       "examples": [
>         "Zm9vYg=="
>       ]
50,51c83,87
<       "required": ["specversion", "id", "type", "source"],
<       "type": "object"
---
>   "required": ["id", "source", "specversion", "type"],
>   "definitions": {
>     "iddef": {
>       "type": "string",
>       "minLength": 1
53c89
<     "id": {
---
>     "sourcedef": {
54a91
>       "format": "uri-reference",
57,59c94,96
<     "time": {
<       "format": "date-time",
<       "type": "string"
---
>     "specversiondef": {
>       "type": "string",
>       "minLength": 1
61c98
<     "dataschema": {
---
>     "typedef": {
63c100
<       "format": "uri"
---
>       "minLength": 1
65c102,105
<     "subject": {
---
>     "datacontenttypedef": {
>       "type": "string"
>     },
>     "dataschemadef": {
66a107
>       "format": "uri",
69c110
<     "type": {
---
>     "subjectdef": {
73,74c114,115
<     "source": {
<       "format": "uri-reference",
---
>     "timedef": {
>       "format": "date-time",
76d116
<     }
78c118,124
<   "type": "object"
---
>     "datadef": {
>       "type": ["object", "string"]
>     },
>     "data_base64def": {
>       "type": "string"
>     }
>   }

[duglin]

Do we have any JSON Schema experts who can review this? @n3wscott @cneijenhuis @fabiojose

[fabiojose]

Why change the file name? With that the changes are no clear for everyone.

Please, keep the same name and perform the changes. Then, if is applicable, create a new PR changing the name.

[fabiojose]

For me keep the original name is better because we are able to see the changes using GitHub tools, instead of merge diffs.

[tsurdilo]

@fabiojose updated. there is no need to do another pr, updated this one. thanks.

[fabiojose]

LGTM

[JemDay]

$schema should be : "http://json-schema.org/draft-07/schema#"

Can somebody verify if this is correctly structured, typically the "definitions" section lives at the same level as "properties" whereas in this submission it's a child.

Not to say this isn't correct, but we've typically followed the pattern/example shows here : http://json-schema.org/understanding-json-schema/structuring.html

[tsurdilo]

@JemDay updated the schema keyword uri.
definitions and properties are on the same level.

[JemDay]

Thanks @tsurdilo..

LGTM

[tsurdilo]

Added contentEncoding=base64 to data_base64 according to @deissnerk comment on issue: #558 (comment)

[deissnerk]

LGTM

[duglin]

Approved on the 2/27 call