Do non-LDO keywords belong in Hyper-Schema?

[handrews]

[Marked as a question b/c I have no proposal I am pushing here- this has just come up several times so we should clarify whether that involves a spec change or not]

Several hyper-schema keywords could potentially be used without using "base" or "links"/LDOs. Are they in the right place?

• "readOnly" and "deprecated" are useful for any sort of data definition, including resources managed in a local database (typically not managed as hypermedia)

• "media" is not unlike "format" in that it provides additional information on interpreting a primitive data type. At least one discussion here has involved someone wanting to use "media" without any other Hyper-Schema features (I'll link to it next time I run across it, i don't remember where it is now)

This issue can be split if the discussions for different keywords go in different direction.

An alternative would simply be to offer guidance (perhaps on the web site) on whether and how implementations can use part of Hyper-Schema. Declaring something to be a Hyper-Schema (via "$schema" and simply not using "base" and "links" may be the right answer, and we just need to clearly document that. The only requirement would be the obvious one that such usage cannot re-define those keywords.

This parallels discussions in the UI and code generation vocab discussions, which are talking about restricting usage of validation keywords.

[dlax]

Several hyper-schema keywords could potentially be used without using "base" or "links"/LDOs. Are they in the right place?

I think they'd be better elsewhere, probably in the "validation" document.

• "readOnly" and "deprecated" are useful for any sort of data definition, including resources managed in a local database (typically not managed as hypermedia)

Could be in "Metadata keywords" section of validation spec. I think it'd make sense to have them along with "default" and "examples".

• "media" is not unlike "format" in that it provides additional information on interpreting a primitive data type. At least one discussion here has involved someone wanting to use "media" without any other Hyper-Schema features (I'll link to it next time I run across it, i don't remember where it is now)

Could be in a section in its own like is "format". (I also often wanted to to use it without hyper-schema.)

[handrews]

Having since taken a quick pass at clarifying the scope and nature of Hyper-Schema in PR #366, it's even more obvious how I had to tack on extra wording to explain why these are there. Without these, you can talk about Hyper-Schema just as a serialization of the abstract Web Linking model, attached to the link context via JSON Schema validation. Which seems very nice and focused to me.

I agree with your ideas about where to put them. It also occurs to me that "media" could be a format, although there are some things to think through for that, and it's probably better to keep it separate.

[dlax]

Henry Andrews a écrit :

I agree with your ideas about where to put them. It also occurs to me that "media" could be a format, although there are some things to think through for that, and it's probably better to keep it separate.

If the idea gets a general approval, I can commit to write a PR.

[handrews]

@dlax it would be great if you could write a PR :-)

I think there are a few things to hammer out (and I want to let other folks have a chance to comment- given the radio silence from a few of the usual suspects I suspect summer vacations are going on right now).

For "readOnly" and "deprecated" , there's a question about whether they should be booleans in the properties, or arrays one level up as with "required". #364 covers "readOnly" and this is mentioned in the main "deprecated" issue, #74.

We don't have to resolve those before moving the properties, but if we do those things, it would be best to do both them and the move in this draft.

For "media", I want to think about why it is an object with sub-keywords (which we don't do for anything else but the LDO which is a very distinct thing). We could have, say, "formatEncoding" and either allow media types (or ranges) as formats (which would mix an open-ended set of values with a specifically listed set, which is probably undesirable) or perhaps it would make sense to have "formatMediaType" or "formatMedia" or something.

I'm not all that attached to any of these options, just want to kick them around while we give folks a chance to see this.

[handrews]

@dlax I dug through all of the old drafts and discovered something interesting: what's now "media" (with sub-keywords) started out as "contentEncoding" (in the validation section) and "mediaType" (in the Hyper-Schema section, but applied to the context, not to the target like the "mediaType" in the LDO which was added much later).

I think the original approach was better, perhaps with "contentMediaType" for symmetry.

I also now think that it would be best to keep this separate from "format", as doing validation based on either should be optional, and I'm willing to bet that while "format" will often be used and supported for validation, "contentEncoding".

@dlax does this sound reasonable to you? If so, a PR removing "readOnly" and "media" from Hyper-Schema and adding "readOnly" to the meta-data section of the validation spec, and "contentEncoding" and "contentMediaType" in the semantic section with "format" somehow would be great.

Let's hold off on switching "readOnly" to an array and adding "deprecated". Those concerns are really orthogonal to where the keywords are defined so probably best to go one step at a time.

[handrews]

Feel free to do a PR now, but be aware that since this has only been up for a few days, other team members may pop up and shoot it down. We can also leave this open for a while for further comment.

A PR like this with implications for implementors will need to stay open for a minimum of 14 days for feedback (which is why I haven't merged "description" as an LDO keyword yet..

[dlax]

@handrews Just submitted a PR about readOnly. Will look at media as soon as I can.