"profile" media type parameter usage #222
Comments
|
It's my understanding we can update the JSON media type registration to add the 'profile' parameter -- with the same semantics as expected, nothing JSON Schema specific. Let's keep investigating this. |
|
@awwright oh cool, glad you've thought of this. Yeah, let's keep this issue open to track that dependency. Would it make sense to create an "RFC" milestone to group issues that need to be handled before RFC but are not directly part of the draft iteration process? |
|
On 2017-01-15 12:25, Austin Wright wrote:
It's my understanding we can update the JSON media type registration to
add the 'profile' parameter -- with the same semantics as expected,
nothing JSON Schema specific. Let's keep investigating this.
please keep in mind that from the way RFC 6906 defines profiles, schemas
are not profiles. what would be a profile of JSON is for example I-JSON
a la RFC 7493 (i.e., it's still just JSON, but a more constrained
version of it). for more background, please refer to RFC 6906, and maybe
to this:
http://dret.typepad.com/dretblog/2016/05/resource-profiles-and-types.html
|
|
As I understand that was about the link relation types, this is about the
media type parameter.
…On Jan 15, 2017 20:53, "Henry Andrews" ***@***.***> wrote:
@dret <https://github.com/dret> you and @awwright
<https://github.com/awwright> had this conversation in #26
<#26> and you
gave your approval. What's changed?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#222 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAatDfU-QEN9qvmeWVYZb283FE9yJ9xdks5rSunWgaJpZM4La9ie>
.
|
|
I'm guessing there is one point of view that looks at a schema as defining a (possibly extremely) restricted subset of JSON, and the other that views it as carrying more meaning than that. Looking @dret's example of I-JSON, that's a generally usable subset of JSON. Schemas are there to constrain the set of documents to a specific use, which is conceptually a very different thing. So if that's an ideal example (and since @dret wrote the profile spec we can assume it is), I'm likely to agree that schemas are not profiles. I think it is critical to be able to request conformance to a schema through media type negotiation, so we should make that possible. We may need to choose or invent another relation, though. I'd like to use an existing one (and likewise a media type parameter that would be recognizable) if possible, but only if it actually fits. |
|
On 2017-01-15 20:22, Henry Andrews wrote:
@awwright <https://github.com/awwright> , @dret
<https://github.com/dret>'s comment about schemas not being profiles
(and the blog post he linked) are not specific to link relation or media
type parameter. A profile is semantically a profile either way it's
expressed, that's the point of allowing both expressions, really.
agreed on this one. the fundamental question is whether a schema *is* a
profile or is not. i don't think it is, but that's just my opinion,
based on how i see schemas and profiles. i do not have the authority to
"approve" how people use profiles. all i can say is that when i wrote
the spec, i had different scenarios in mind, and i have tried my best to
explain how they are different from schemas.
if people still think that they want to use profiles as a way to signal
schemas, then this is what is going to happen. as mentioned in the blog
post and elsewhere, link relations are sufficiently fuzzy to make it a
futile exercise to try to use spec exegesis to determine whether that's
right or wrong.
personally, i would think that "type" is much more fitting for this
scenario, but that spec is equally fuzzy.
coming back to the podcast example from the spec: i'd expect the "type"
of a feed to link to the schema, linking the instance to the way how the
class is defined. and in some cases i'd expect the "profile" of a feed
to identify the fact that a feed indeed is a podcast, making it explicit
that the specific feed instance follows all the podcast rules, while
still being a legitimate feed.
|
|
On 2017-01-15 20:30, Henry Andrews wrote:
Looking @dret <https://github.com/dret>'s example of I-JSON, that's a
generally usable subset of JSON. Schemas are there to constrain the set
of documents to a specific use, which is conceptually a very different
thing. So if that's an ideal example (and since @dret
<https://github.com/dret> wrote the profile spec we can assume it is),
I'm likely to agree that schemas are not profiles.
thanks, and good to hear that at least my point of view makes some
sense. not everybody might agree with it, but that's a different thing.
|
|
@dret said:
Yeah, I noticed that :-/ I agree that it seems to be the closest one. Perhaps we can simply define and register a media type parameter for specifying type analogous to the profile one? I have on idea whether that sort of thing is likely to be embraced or frowned upon in the IETF. |
|
On 2017-01-17 12:24, Henry Andrews wrote:
@dret <https://github.com/dret> said:
I agree that it seems to be the closest one. Perhaps we can simply
define and register a media type parameter for specifying type analogous
to the profile one? I have on idea whether that sort of thing is likely
to be embraced or frowned upon in the IETF.
my feeling is that if it's defined and used and deployed, you might get
through with it. but JSON is an important thing, so doing anything that
involves core JSON specs is not going to happen easily.
one question you could ask yourself is whether you really need this as a
media type parameter. XML, which is rather schema-centric, never had it
and simply had a variety of embedded signals, depending on the schema
language (for example, DTD and XSD have their own way of doing it). that
seemed to work well enough, and in scenarios where you want to signal
the schema outside of the instance, you simply have to make that part of
your protocol design.
|
|
@dret part of the point of REST is to not design your own protocols :-P What I want out of the media type parameter is to be able to manage API evolution by allowing a client to signal which representations (as indicated by schema URIs which may include a version) they understand. This is not a concept I've been able to test on a large scale yet, so I am also still looking into other options. But this is the one that is most appealing and flexible so far.
A schema media type parameter seems ideal. It lets me version the thing that actually changes: the structural details of the representation. I can put multiple schema versions in if the representation is potentially usable to clients who know different schemas (if it validates, it's usable- if a client isn't impacted by a new field, the new field's presence should not automatically break things). I am very interested in other ideas on the topic of API evolution, though, and don't consider this a settled solution at all. |
|
@dret the solution may be to define |
|
@dret with regards to your XML comparison, we've really avoided putting any requirements on the content of the JSON instance document aside from what is actually required by the schema. I want JSON Schema to be usable with any JSON document, including JSON document formats that were not initially built with JSON Schema in mind (e.g. legacy API formats). I am sure I could find a way to make things work without a media type parameter. The content negotiation abilities would not be there, but clients could just look through the link headers (which is already one of the options we offer with "describedBy" links, although the more I look at it the more I think "type" is more appropriate). It makes the client do a bit more work but the fundamental capabilities are all still there. Maybe that's what you meant by defining a protocol? |
|
On 2017-01-17 12:53, Henry Andrews wrote:
@dret <https://github.com/dret> with regards to your XML comparison,
we've really avoided putting any requirements on the content of the JSON
instance document aside from what is actually required by the schema. I
want JSON Schema to be usable with any JSON document, including JSON
document formats that were not initially built with JSON Schema in mind
(e.g. legacy API formats).
just as more historical notes: both DTD and XSD (and all other XML
schema languages i've ever seen) do not put any requirements on what
instances must say. they just have well-defined instance-based signals.
and depending on the scenario, you might want to ignore those instance
signals anyway. for example, if you submit data into my processing
pipeline, i don't care which schema you declare it adheres to. i will
check against my schema that i think is the best way to accept or reject
data for that specific pipeline.
|
|
What I see "profile" accomplishing in JSON Schema is exactly what the RFC claims: It's enabling clients to comprehend additional semantics about a document. For example, a podcast profile of JSON. My understanding of "type" is from the RDF sense, it's the most generic kind of membership you can get: An assertion that some resource is an "instance" in some non-terminated, open set. In this understanding, it seems to be that "profile" is a special kind of "type" relationship. I'm not suggesting a profile should imply there's a JSON Schema, but rather some profiles on JSON documents will have a document describing that profile (i.e. vocabulary) in a machine readable fashion, which is useful in RESTful applications. I think having "profile" as a media type parameter is useful because that enables Content-Type negotiation. This is especially useful for a syntax that is very brittle. However, perhaps it could be a separate document altogether to emphasize this isn't a JSON Schema thing. |
|
@awwright From looking at JSON-LD's use of profile (it defines three for As we look towards Draft 07 and beyond, I think we should consider the "type" relation, and look for a good way to enable content negotiation based on either that or a more specific "schema" relation and parameter. I really don't see how our use of profile can be squared with its definitions or with examples such as I-JSON and JSON-LD |
|
I suppose @dret would be the expert on that subject. To put my viewpoint another way, "type" just doesn't convey the same meaning to me. A resource might have a "type" of Car (an instance of a Car), or be an instance of Process, or something. It just classifies resources. A profile might be used to express syntactical restrictions sure, but also vocabulary restrictions. HTML uses "profile" in the vocabulary fashion (as seen in HTML 4.01, here's a proposal to add it to HTML5). There's a lot of nuance here that's probably getting glossed over, let me see if I can take some time to understand it. |
|
@awwright I agree that that definition of profile makes sense for use here, but that's not the definition declared in the RFC and registered as a link relation with the IANA. I'm not dead set on "type", it just happens to be around and close. There is also "describedby" which is pretty vague and people seem to talk about it pointing to docs more than machine readabile thing (that's a casual assertion, not backed up with anything resembling proof). "schema" would not seem totally out of the question, if we end up defining our own. It's frustrating that not all standards use the same term in the same way, but as much as the HTML proposal fits (seems to have been abandoned for nearly 7 years, though), the more well-established definition does not. |
|
On Jan 31, 2017, at 07:04, Henry Andrews ***@***.***> wrote:
@awwright I agree that that definition of profile makes sense for use here, but that's not the definition declared in the RFC and registered as a link relation with the IANA.
"schema" would not seem totally out of the question, if we end up defining our own.
It's frustrating that not all standards use the same term in the same way, but as much as the HTML proposal fits (seems to have been abandoned for nearly 7 years, though), the more well-established definition does not.
get in touch if there is interest in defining and registering a "schema" link relation type, i'd be willing to help.
|
|
Hey all, After a few days going through Dr. Fielding's work, reading up on Media Types, related RFC specs, few blog articles, and github issues I ended up here. In an effort to implement REST, I'm trying to find concrete ways to achieving the following: I think a combination of application/json and hyperschema would achieve this. Which I think coincides with @handrews comment #222 (comment) Here's a couple resoures that helped me get here: Profile parameter to define the representation Media type for content negotiation, though using a vendor tree. Now it seems the question is whether to use "profile" parameter or create another one, "schema". Profile: Cons: Schema: Couldn't we register schema to be a media type level parameter, and not specific to json? My vote is with using profile, though I don't think we can go wrong with either option. |
|
@jam01 thanks for commenting, this is great! I am personally leaning more towards trying to register "schema" as a link relation and media type parameter. Content negotiation via schema URI in a media type parameter is essential to the API evolution approach that I want to take, as I've no doubt mentioned above (can't be bothered to re-read all of my comments in detail right now :-) As for media type parameters and specificity to JSON, the media type has to declare what parameters it accepts. So we can specify that a particular link relation is intended to be used with the same semantics in a media type parameter, but each media type has to choose to use it. Of course, if you make a vendor +json type, you can put whatever parameters you want on it. I'd rather use a parameter with We're on the verge of publishing another draft in the next few days/week or so, but I'd really like to get this and other core aspects nailed down in the following draft. It would be good to settle on the core stuff and give folks confidence that it will be as stable as a draft can be expected to be. I also want to explore ideas around how JSON Schema can integrate with JSON-LD. I've discussed this with one of the editors of the JSON-LD spec and we both feel like there's something there, but the details are vague. I'd like the idea of being able to declare JSON Schema vocabularies through JSON-LD instead of (or more likely in addition to?) the |
|
👍 for attempting to use JSON-LD :-) |
|
Having surveyed the current state of the world here, I am going to go ahead with #351 As noted at various points above, we can propagate media type features such as content negotiation parameters and fragment identifier syntax to As for "profile":
Therefore I will be taking "profile" out while adding This will be done as a single PR with #351 as it is a direct replacement of one solution with another. |
|
@akuckartz for JSON-LD + JSON Schema discussion, please see #309 (or if that is not quite right, please file a new issue). I'm still interested in this, I would just like to consider it separate from "profile" |
This change removes "profile", since as noted in issue json-schema-org#222 the usage is not correct. It replaces it with "schema", with the minimal possible change. We may wish to also remove the "describedby" link relation and instead mandate using "schema", or a similarly named extension relation, and allow downloading schemas based on the parameter. That is outside of the scope of this change.
|
Merged #414. |
ghost
removed
the
gregsdennis
added
clarification
In mnot/I-D#175 @dret states:
yet in issue #26 filed here by @dret it looked like we had received his approval on how we are wording our specification around the use of "profile"
@dret can you help us out here? Is what we have acceptable or not? To me it seems like JSON Schema is doing exactly this- further constraining the
application/jsonmedia type by declaring that only a subset of possible documents are valid rather than all possible expressions of the JSON syntax. But it sounds like you do not view it this way.Also in the same issue in mnot/I-D:
Since
application/jsondoes not explicitly specifyprofileas a media type parameter, does that mean that even if "profile" is correct we cannot use it withapplication/json? Do we need to specify anapplication/instance+jsonmedia type in order to add a parameter (whether it is "profile" or not?) Honestly my entire API evolution strategy relies on having schema URIs in a media type parameter so it's a huge problem for me if we can't do this somehow.The balkanization of IETF standards is immensely frustrating. "Look, here are these two great ideas that do not conflict in any way and perfectly complement each other, but you cannot use them together because the two RFC authors did not coordinate and/or wrote their RFCs at different times!"
Finally:
@dret if aspects of this distinction are relevant to JSON Schema and not covered in #26 could you please elaborate?
The text was updated successfully, but these errors were encountered: