search

json-schema-org / json-schema-spec

The JSON Schema specification
http://json-schema.org/
Other
3.69k stars 259 forks source link

Link directly to targets #1536

Open gregsdennis opened 1 day ago

gregsdennis commented 1 day ago

With the spec docs now in markdown and with us self-hosting the files, should we move to having links go directly to their targets rather than to an appendix (which is IETF style)? Personally, I never liked linking to an appendix.

OpenAPI uses direct links, which you can see with the JSON Schema spec link in Section 4.4.

jdesrosiers commented 22 hours ago

I agree. The appendix is unnecessary.

gregsdennis commented 13 hours ago

I'm happy for anyone who wants to do this to take it.

For references to specific sections of the target, the links should go directly to that section (or as close as possible).

SanidhyaMadheshia commented 2 hours ago

I think an appendix is not preferred by many contributors . And if direct linking enhances usability without sacrificing clarity, it could be a beneficial shift.