search

manton / JSONFeed

The JSONFeed.org website
Creative Commons Zero v1.0 Universal
943 stars 55 forks source link

Official JSON Schema #90

Open sonicdoe opened 7 years ago

sonicdoe commented 7 years ago

In https://github.com/brentsimmons/JSONFeed/issues/82#issuecomment-304655237 @manton expressed interest in an official JSON Schema for JSON Feed:

I've seen at least 2 schemas and I'm not sure that one is really the "official" one yet. I'd love to see some consensus from the community on that. I haven't looked closely enough at the schemas to know which one is best or if differences can be merged to create a more complete version.

As far as I am aware, both @madskristensen and I have created schemas so far. See also #14, #21, #80, and #82.

To make progress towards an official schema, I have gone through SchemaStore/schemastore’s JSON Feed schema and sonicdoe/jsonfeed-schema. Here are the most notable differences:

I’ve intentionally tried not to make any judgments in the above list. I’ll try to go into more detail about the decisions I have made in jsonfeed-schema tomorrow so that we can discuss the up- and downsides of both approaches.

sonicdoe commented 7 years ago

schemastore describes every property using description

Adding description to every property is quite noisy and makes the schema harder to read, in my opinion. Additionally, it makes using $ref more difficult as you can’t place a description right next to it. I think it’s best to rely on the descriptions in the official spec.

schemastore specifies a more forgiving version property

Specifically, schemastore allows version to be any URL, jsonfeed-schema only allows the exact string https://jsonfeed.org/version/1. See https://github.com/brentsimmons/JSONFeed/issues/31#issuecomment-302615821 for why I use this (more strict) specification.

schemastore uses a different regex (^_[a-zA-Z]([^.]+)$) than jsonfeed-schema (^_\\w[^.]*$) for extensions

At second glance, both schemastore’s and jsonfeed-schema’s regex weren’t fully matching the spec’s definition. I have now updated my regex to ^_[a-zA-Z][^.]*$ which allows extensions like _x.

schemastore specifies the about property in extensions

The spec says that the about property is optional but that it should appear at least once in a feed. Because this is difficult to validate using a JSON Schema, I’d rather pass on this.

schemastore allows item.id to be a number, jsonfeed-schema only allows a string

See https://github.com/brentsimmons/JSONFeed/issues/60#issuecomment-303446537 for why I only allow strings.

schemastore specifies uniqueItems on item.tags

I think this makes sense. However, if we were to validate this, it should also be mentioned in the spec.

madskristensen commented 7 years ago

schemastore describes every property using description

The description is important because it is being used by supporting editors like Visual Studio and IntelliJ to provide hover tooltips.

schemastore specifies a more forgiving version property

The spec wasn't clear so I left the version as a uri type instead of a fixed enum value

schemastore uses a different regex (^a-zA-Z$) than jsonfeed-schema (^\w[^.]*$) for extensions

Great if you have an improved regex for it. Thumbs up!

schemastore specifies the about property in extensions

That's because it's the only property in the specification for extension objects. Validating that you should have at least one in the document is very difficult to do, so I'm passing on that as well.

schemastore allows item.id to be a number, jsonfeed-schema only allows a string

String-only makes sense to me

schemastore specifies uniqueItems on item.tags

I did that because it seems to be a usual best practice when I look at similar JSON formats

madskristensen commented 7 years ago

@sonicdoe

Adding description to every property is quite noisy and makes the schema harder to read, in my opinion. Additionally, it makes using $ref more difficult as you can’t place a description right next to it. I think it’s best to rely on the descriptions in the official spec.

You can easily use descriptions and $ref in the same property, by putting the $ref inside an allOf array.

manton commented 7 years ago

Thanks everyone. This discussion is very valuable, since I personally have limited experience with JSON Schema.

I've been experimenting with a validator. For now, it is based on the schemastore schema linked above. I picked it because it was honestly the first one I saw. We can and should change it as needed.

http://validator.jsonfeed.org/

The source is here. It could use many improvements. Pull requests on the schema file itself are also welcome: https://github.com/manton/jsonfeed-validator/tree/master/config

sonicdoe commented 7 years ago

The description is important because it is being used by supporting editors like Visual Studio and IntelliJ to provide hover tooltips.

Thank you, @madskristensen, this totally makes sense. I have now also added property descriptions.

I've been experimenting with a validator. For now, it is based on the schemastore schema linked above. I picked it because it was honestly the first one I saw. We can and should change it as needed.

@manton If you are interested, jsonfeed-schema is now also available on RubyGems. However, I’m also happy to submit pull requests directly to the schema in your repository.

ghost commented 7 years ago

Advise standards body involvement in standards creation process. Like XML, JSON has potential security vulnerabilities (well documented, just search). As a result the historical knowledge of a standards body could make a world of difference getting a valuable JSON feed off the ground.

OASIS, for example, may have the ability to switch between Atom and JSON on the fly. Might be a good entry point for seeking an interoperable spec for JSON bleed:

http://docs.oasis-open.org/odata/odata-atom-format/v4.0/odata-atom-format-v4.0.html http://docs.oasis-open.org/odata/odata-json-format/v4.0/odata-json-format-v4.0.html

froschdesign commented 4 years ago

Any progress on this topic?

Currently, it is cumbersome to implement a JSON feed without validating the result. A JSON schema opens the door for correct feed output no matter what programming language is used. And a schema for each version allows to support the current version 1.0 and 1.1 and also all future versions.

manton commented 4 years ago

Nothing new, but we did use schemastore's JSON schema from earlier in the thread to build https://validator.jsonfeed.org/. It would be good to update it for JSON Feed 1.1 and make sure that whatever becomes the "official" schema is linked from the main site.

froschdesign commented 4 years ago

@manton

we did use schemastore's JSON schema

Good to know.

It would be good to update it for JSON Feed 1.1 and make sure that whatever becomes the "official" schema is linked from the main site.

This is absolutely necessary and at the same time the website should updated. "Announcing" and "2017" is no longer relevant. 😉

sonicdoe commented 4 years ago

I’ve published jsonfeed-schema v0.5.0, adding support for the recently-released JSON Feed Version 1.1.