search

json-schema-org / json-schema-spec

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

Explain why plain name fragments are as they are #1293

Closed handrews closed 2 years ago

handrews commented 2 years ago

Because XML is/was the most likely need for cross-media-type fragment identifiers.

Fixes #901

jdesrosiers commented 2 years ago

Right now, the spec is quite bloated with things that don't necessarily belong in a specification. Mostly I think that's because we didn't really have anywhere else to put things, but that's not the case anymore. This strikes me as maybe something that should be a blog post or maybe an ADR.

handrews commented 2 years ago

@jdesrosiers I could see it as an ADR. I don't think it's actually interesting enough for a blog post. I've been thinking of writing ADRs for some decisions that people still ask about just to document them. Although sometimes trying to make it fit the ADR format when I can't even remember what the alternatives were is a bit annoying.

handrews commented 2 years ago

@jdesrosiers I considered making this an ADR, but it doesn't fit the format well because we kind of inherited this and assembled our own justifications for keeping it. There wasn't really a clear decision point.

I also noticed that it's weird that the Fragment Identifiers section doesn't actually define the plain name syntax, which instead appears in the section of $anchor and $dynamicAnchor, where its source is less clear.

So I've removed the editorial explanation about XML and APIs, moved the syntax up to the Fragment Identifiers section, and added one extra line so that the reason for using NCName is clear. Given the bewildering constellation of XML specifications, the additional link is, I think, useful as an informative reference. But I'm open to counter-arguments.