JSON Hyper Schema
Kris Zyp
data, based on discussions [2] from restful-json group on using a
meta-specification for describing links in JSON data:
[1] http://www.json-schema.org/draft-hyperschema-01.txt
[2] http://groups.google.com/group/restful-json/browse_thread/thread/cf4b0bd444f5fd83
included here:
The Hyper Schema Media Type
This proposal defines a format for describing the structure of hypertext
linking and metadata information in JSON-based media types with JSON
Schema (suggested to be application/json+schema). The mechanism for
defining links and metadata can be applied to any JSON media type, and
enables hypertext navigation through data structures that are
represented by JSON. This proposal does not require target JSON media
types (those being described by the hyper-schemas) to follow any
specific structure.
1. Introduction
Hyper Schema media documents builds on JSON Schema to provide a format
for describing the structure of other JSON representations (instances).
This schema can be used to define the required type and constraints on
property values, as well as define the meaning of the property values
for the purpose of describing a resource and determining hyperlinks
within the representation. Hyper Schema acts as a meta-document.
1.1. Design Considerations
This media type does not attempt to dictate the structure of JSON
representations that contain data, but rather provides a separate format
for flexibly communicating how a JSON representation should be
interpreted, such that user agents can extrapolate hyperlink information
with the JSON document. This specification does not define a protocol.
The underlying protocol (such as HTTP) should sufficiently define the
semantics of the client server interaction and the retrieval of resource
represenations linked to by JSON representations. The goal of this
format is to sufficiently describe JSON structures such that one can
utilize latent identification information available in existing JSON
representations from a large variety of services that leverage a REST
architecture using existing protocols.
1.2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
The grammatical rules in this document are to be interpreted as
described in [RFC4234].
1.3. Terminology
JSON hyper schemas are an extended form of JSON schema
(http://www.json-schema.org) with attributes specifically designed for
defining the meaning of JSON properties in JSON representations.
An instance representation is a JSON structure that is described by the
hyper-schema.
1.4. Associating instances with schemas.
Instance representations may be of the application/json media type or
any other subtype. Consequently, dictating how an instance
representation should specify its schema is beyond the normative scope
of this document (since this document specifically defines the JSON
hyper schema media type, no other), but it is recommended that instances
specify their schema so that user agents can interpret the instance
representation and messages may retain the self-descriptive
characteristic, avoiding the need for out-of-band information about
instance data. Two approaches are recommended for declaring the
hyper-schema that describes the meaning of a JSON instance's structure
or a collection of instance's structure. A MIME type parameter named
"schema" or a Link header with a relationship of "schema" SHOULD be used:
Content-Type: application/json; schema=http://json.com/my-hyper-schema
or if the content is being transferred by a protocol (such as HTTP) that
provides headers, the Link header can be used:
Link: <http://json.com/my-hyper-schema>; rel="schema"
1.5. Self-descriptive hyper schema
Hyper schemas are themselves instances for the hyper schema for hyper
schemas. A self-describing JSON hyper schema for JSON hyper schemas can
be found at http://json-schema.org/hyper-schema. All hyper schemas
SHOULD include a MIME parameter that refers to the self-descriptive
hyper schema or another schema that extends this hyper schema:
Content-Type: application/json;
schema=http://www.json-schema.org/hyper-schema
2. A hyper schema defines the following attributes in addition to those
attributes that already provided by JSON schema. Just as with JSON
schema attributes, all the attributes in hyper-schema are optional.
Therefore an empty object is a valid (non-informative) schema, and
essentially describes plain JSON (no constraints on the structures).
Addition of attributes provides additive information for user agents.
2.1 hrefProperty
This defines the name of the property that indicates a hyperlink
throughout the hierarchy of instance JSON representations. When this
property is encountered in the instance object or any of it’s child
objects (or arrays), the value of the property indicates target URI of
the hyperlink and is resolved per RFC 2396. The object may include other
properties providing a partial/summary representation of the target
resource. The name of property in which the value is found should imply
the relationship name of the link. For example, if a schema is defined:
{
"hrefProperty": "href"
}
If an instance resource's JSON representation is:
{
"name": "A resource",
"up": {"href": "http://somesite.com/parent"}
}
This would indicate that the "up" property value SHOULD be resolved to
the resource at "http://somesite.com/parent". Implicitly the given
resource is linked to "http://somesite.com/parent" by an "up" relationship.
2.2. link
This indicates that the value of the given instance property is a URI
that should be interpreted as link. The value of this schema property
indicates the name of the relationship to the linked target. The value
of the instance property should be resolved as a URI resolved per RFC 2396.
If the relation value is "self", when this property is encountered in
the instance object, the object represents a resource and the object is
treated as a full representation of the target resource identified by
the specified URI.
For example, if a schema is defined:
{
"properties": {
"id": {
"link": "self"
},
"up_id": {
"link": "up"
}
}
}
And if a collection of instance resource's JSON representation was
retrieved:
GET /Resource/
[
{
"name": "thing",
"id": "resource",
"up_id": "parent"
},
{
"name": "thing2",
"id": "resource",
"up_id": "parent"
}
]
This would indicate that for the first item in the collection, it's own
(self) URI would resolve to /Resource/thing and the first item's "up"
relationship should be resolved to the resource at "/Resource/parent".
2.3. baseURI
This property indicates the baseURI to use to resolve URIs (RFC 2396).
Relative URIs can then be resolved using this resolved URI as a context.
The baseURI value itself can be a relative URI as well (and resolved
according to its context).
2.4. instances
When present, the value of this property MUST be the collection of
instances of this defined schema. This will generally be a link to the
collection URI, by which user agents SHOULD be able to retrieve the
instances with a GET (and possibly query for specific instances), and
user agents SHOULD be able to POST to this target to create new
instances (if such an action is allowed).
2.5 queryEncoding
This property indicates the query encoding format that the server
supports for querying the collection of instances. The query can be
suffixed to the collection URI to query the collection with
property-based constraints on the resources that SHOULD be returned from
the server. For example, with the following schema:
{
"queryEncoding": "application/x-www-form-urlencoded",
"instances":{"$ref":"/Product/"},
"properties":{
"name":{"description":"name of the product"}
}
}
This indicates that the client can query the server for instances that
have a specific name:
/Product/?name=Slinky
2.6. fragmentResolution
This property indicates the fragment resolution protocol to use for
resolving fragment identifiers in URIs within the instance
representations. This applies to the instance object URIs and all
children of the instance object's URIs. The default fragment resolution
protocol is "dot-delimited", which is defined below. Other fragment
resolution protocols may include JSONPath.
The fragment identifier is based on RFC 2396 Sec 5, and defines the
mechanism for resolving references to entities within a document.
2.6.1. "dot-delimited" fragment resolution
With the dot-delimited fragment resolution protocol, the fragment
identifier is interpreted as a series of property reference tokens that
are delimited by the "." character (\x2E). Each property reference token
is a series of any characters except the "." character. Each property
reference token should be interpreted, starting from the beginning of
the fragment identifier, as a path reference in the target JSON
structure. The final target value of the fragment can be determined by
starting with the root of the JSON structure from the representation of
the resource identified by the pre-fragment URI. If the target is a JSON
object, than the new target is the value of the property with the name
identified by the next property reference token in the fragment. If the
target is a JSON array, than the target is determined by finding the
item in array the array with the index defined by the next property
reference token (which MUST be a number). The target is successively
updated for each property reference token, until the entire fragment has
been traversed.
For example, for the following JSON representation:
{
"foo":{
"anArray":[
{"prop":44}
],
"another prop":{
"baz":"A string"
}
}
}
The following fragment identifiers would be resolved:
fragment identifier resolution
# self (the root of the resource itself)
#foo the object referred to by the foo property
#foo.another prop the object referred to by the "another prop"
property of the object referred to by the foo property
#foo.another prop.baz the string referred to by the value of "baz"
property of the "another prop" property of the object referred to by the
foo property
#foo.anArray.0 the first object in the "anArray" array
2.7. root
This attribute indicates that the value of the instance property value
SHOULD be treated as the root or the body of the representation for the
purposes of user agent interaction and fragment resolution (all other
properties of the instance objects are can be regarded as metadata
descriptions for the data).
2.8. uriTemplate
This property may be used in conjunction with a link property to
indicate how the target URI should be constructed. The URI should be
constructed using the URI template provided by the value in combination
with the property values of the instance object as variables per
http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.txt.
For example:
{
"properties": {
"children": {
"link":"children",
"uriTemplate": "?up_id={id}"
}
}
}
3. IANA Considerations
The suggested MIME media type for a Hyper Schema is
application/json+schema.
Type name: application
Subtype name: json+schema
Required parameters: n/a
Optional parameters: schema
Example of using JSON hyper schema to define RESTful JSON structures:
JSON-Referencing convention (followed by Persevere and Dojo)
{
"hrefProperty": "$ref",
"properties": {
"id": {
"link": "self"
}
},
"fragmentResolution": "dot-delimited",
"additionalProperties": {"$ref": "#"} // definition applies to all
children as well
}
CouchDB collection schema:
{
"description": "A CouchDB collection",
"properties":{
"rows":{
"root":true,
"type":"array",
"hrefProperty":"id"
},
"total_rows":{
"type":"integer",
"description":"Total number of rows in the DB (may not all
be shown in this response)"
}
}
}
CouchDB document:
{
"type": "object",
"description": "A CouchDB document",
"properties": {
"_id": {
"link": "self"
}
},
}
Example Shoji Catalog Schema:
{
"baseURI": "http://example.org/users/", // in the Shoji example it
seems strange to me that almost all the links seem to be relative to
this URI, yet the resource is identified as http://example.org/users.
"description": "A Shoji catalog",
"properties": {
"self":{
"link": "self"
},
"entities" :{
"items": {
"link": "entity",
"description": "An Shoji entity"
}
},
"views" :{
"items": {
"link": "view",
"description": "An view on the entities"
}
},
"catalogs" :{
"items": {
"link": "sibling",
"baseURI": "/", // should be resolved from the root of
example.org
"description": "A Shoji catalog"
}
}
}
}
Shoji Document:
{
"properties": {
"self":{
"link": "self"
},
"body": {
"root": true,
}
}
}
Questions:
How should we escape '.' in the dot-delimited fragment resolution
protocol (while still allowing the empty string as a property name)?
Is the uriTemplate property worth the complexity? Most REST APIs can be
described without it, and it forces a lot of complexity on user agents?
Should the "link" property be "link" or "relation" or "reference"?
Should the URIs in the recommended MIME parameter that refer to the
schema be quoted?
Thanks,
Kris
Dean Landolt
Either this is a little confused or I'm a little slow (perhaps both), but is this equivalent to <a href="/Resource/thing" rel="self"> and <a href="/Resource/parent" rel="up"> respectively? How's that? For the former, where does the "name" property get its semantics from? I'm still not clear exactly what "self" implies. To me it imples that both resources in the array can be retrieved via GET /Resource/resource -- which is ambiguous.
2.6. fragmentResolution
This property indicates the fragment resolution protocol to use for
resolving fragment identifiers in URIs within the instance
representations. This applies to the instance object URIs and all
children of the instance object's URIs. The default fragment resolution
protocol is "dot-delimited", which is defined below. Other fragment
resolution protocols may include JSONPath.
Where is it defined the means by which another protocol can be specified? Given "dot-delimited" is normative, shouldn't how to reference another protocol at least be spelled out? For instance, would JSONPath fragments be specified like so: "fragmentResolution": "JSONPath", or some other way (perhaps, via a ref somehow)?
Questions:
How should we escape '.' in the dot-delimited fragment resolution
protocol (while still allowing the empty string as a property name)?
Since fragments are transferred over the wire, concerns about original encoding not being preserved (I'm looking at you, WSGI) are a non-issue. IIRC in browser user agents client scripts should have access to the naked, undecoded href. If this is true across the board, why not standardize on splitting on the "." character (\x2E) before decoding, and then decode each piece individually. That way any string could contain a %2E (or any other encoded char, though that seems unnecessary). For example, a structure like so:
{
"foo": "bar",
"foo.bar": {
"baz": ["a", "b", "c"]
}
"foo.bar.baz": "quux"
}
...could be navigated like so:
#foo => "bar"
#foo.bar => "bar" (no "bar" as child of "foo")
#foo%2Ebar.baz => ["a", "b", "c"]
#foo%2Ebar.baz.1 => "b"
#foo%2bar%2baz => "quux"
Is the uriTemplate property worth the complexity? Most REST APIs can be
described without it, and it forces a lot of complexity on user agents?
I haven't finished looking through Gregorio's proposal yet, but it does look pretty complex. But cool. Perhaps it could be optional? I don't understand the implications well enough to discern if that's feasible though.
Should the "link" property be "link" or "relation" or "reference"?
If I understood link correctly, it looks like it defines what property is the "rel", in html terms. If this is the case, I imagine rel, relation, or relationship would be more descriptive.
Should the URIs in the recommended MIME parameter that refer to the
schema be quoted?
The ";" character is reserved (RFC 1738) -- what else would need escaping in the header value? I've seen it both ways -- can you allow both?
Dean Landolt
Should the "link" property be "link" or "relation" or "reference"?
If I understood link correctly, it looks like it defines what property is the "rel", in html terms. If this is the case, I imagine rel, relation, or relationship would be more descriptive.
It just occurred to me that if link is equivalent to the rel property on A and LINK tags, why not use the convention implied by hrefProperty and just call it relProperty? Also, would it make sense to also specify the corresponding revProperty (though I noticed they left that out of html5)? There are a lot of other properties that have hypertextual semantics -- I could certainly see the benefit of a titleProperty (for accessibility at least). What about an idProperty and/or nameProperty (for fragments in particular), or is all this overkill? Or am I just totally missing the mark on the intent of "link"?
Dean Landolt
Just to bludgeon this dead horse, it may be worthwhile to point out the link types spec (more accurately, the semantics of the rel property) per html4 [1]
First the spec defines the rules (whitespace as separator, case insensitive, extensible, extensible via profile -- which is kinda interesting), then it codifies a number of commonly used link types and their interpretations. For instance, "alternate":
Is there any plan to codify common relationships in JSON Hyper Schema? Would it be good enough to use just what's in the html spec? I could see the benefit of the "stylesheet" type should someone ever define jss (JSON Stylesheet, err, application/style+json: there are a few yaml or yaml-like css interpretations floating around, I could imagine a json serialization being a useful means for markup, first via a client script but eventually perhaps with user-agent support, a la xml). Looking down the list, they all look like they may have their place.
One quibble I've always had with the above-referenced list (or, with html in general) is the lack of explicit transclusion support. The distinction between a transclusion and other types of references is fairly important, perhaps moreso when it comes to json. It would be useful to formalize this relationship type.
[1] http://www.w3.org/TR/WD-html40-970917/struct/links.html#h-13.3.2
Kris Zyp
Yeah, I totally screwed up the example. It should be:
[
{
"id": "thing",
"up_id": "parent"
},
{
"id": "thing2",
"up_id": "parent"
}
]
Hopefully that makes more sense.
>
> 2.6. fragmentResolution
>
> This property indicates the fragment resolution protocol to use for
> resolving fragment identifiers in URIs within the instance
> representations. This applies to the instance object URIs and all
> children of the instance object's URIs. The default fragment
> resolution
> protocol is "dot-delimited", which is defined below. Other fragment
> resolution protocols may include JSONPath.
>
>
>
> Where is it defined the means by which another protocol can be
> specified? Given "dot-delimited" is normative, shouldn't how to
> reference another protocol at least be spelled out? For instance,
> would JSONPath fragments be specified like so: "fragmentResolution":
> "JSONPath", or some other way (perhaps, via a ref somehow)?
I had kind of just left that open-ended (kind of like HTTP's range
units) for future extensions, but yes, that would probably be good to
spell out more clearly.
>
>
> Questions:
>
> How should we escape '.' in the dot-delimited fragment resolution
> protocol (while still allowing the empty string as a property name)?
>
>
>
> Since fragments are transferred over the wire, concerns about original
> encoding not being preserved (I'm looking at you, WSGI) are a
> non-issue. IIRC in browser user agents client scripts should have
> access to the naked, undecoded href. If this is true across the board,
> why not standardize on splitting on the "." character (\x2E) before
> decoding, and then decode each piece individually. That way any string
> could contain a %2E (or any other encoded char, though that seems
> unnecessary). For example, a structure like so:
>
> {
> "foo": "bar",
> "foo.bar": {
> "baz": ["a", "b", "c"]
> }
> "foo.bar.baz": "quux"
> }
>
> ...could be navigated like so:
>
> #foo => "bar"
> #foo.bar => "bar" (no "bar" as child of "foo")
> #foo%2Ebar.baz => ["a", "b", "c"]
> #foo%2Ebar.baz.1 => "b"
> #foo%2bar%2baz => "quux"
>
You're right. I think I was originally concerned that that wouldn't work
well with Firefox which automatically decodes fragments as soon as you
enter them in the address bar (even changes what is show in the address
bar), thus you couldn't have a URL which disambiguates between
properties like in your example, and could also be used to refer to
different anchor tags in an HTML representation of the same resource.
However, I think trying to preserve full parity is a lost cause, as
there are already plenty of valid characters in JSON property names that
are illegal in HTML anchor names. Your encoding strategy doesn't really
add significant limitation, so I agree, that is the way to go.
>
>
> Is the uriTemplate property worth the complexity? Most REST APIs
> can be
> described without it, and it forces a lot of complexity on user
> agents?
>
>
>
> I haven't finished looking through Gregorio's proposal yet, but it
> does look pretty complex. But cool. Perhaps it could be optional? I
> don't understand the implications well enough to discern if that's
> feasible though.
>
Yes, and the specification is intentionally written such that nothing
relies on uriTemplate, it only necessary for variable replacement
generated URLs (not just relative URL resolution), so it could easily be
ignored if the complexity is too much for user agents.
>
> Should the "link" property be "link" or "relation" or "reference"?
>
>
>
> If I understood link correctly, it looks like it defines what property
> is the "rel", in html terms. If this is the case, I imagine rel,
> relation, or relationship would be more descriptive.
Yes, although it somewhat analogous to the entire anchor. Its kind of
like the element (saying there is a link here) and attribute (saying
what the relationship is), the whole shebang. But the value of the
property is certainly acts like "rel".
>
>
> Should the URIs in the recommended MIME parameter that refer to the
> schema be quoted?
>
>
>
> The ";" character is reserved (RFC 1738) -- what else would need
> escaping in the header value? I've seen it both ways -- can you allow
> both?
>
and the other email...
Dean Landolt wrote:
>
>
> On Thu, Jul 30, 2009 at 12:09 PM, Dean Landolt <de...@deanlandolt.com
> <mailto:de...@deanlandolt.com>> wrote:
>
> Should the "link" property be "link" or "relation" or
> "reference"?
>
>
>
> If I understood link correctly, it looks like it defines what
> property is the "rel", in html terms. If this is the case, I
> imagine rel, relation, or relationship would be more descriptive.
>
>
>
> It just occurred to me that /if/ link is equivalent to the rel
> property on A and LINK tags, why not use the convention implied by
> hrefProperty and just call it relProperty?
>
The "hrefProperty" and the "link" attributes have very different
semantics and purposes. The hrefProperty defines the name of the
property that may exist anywhere within a JSON structure to define a
link, allowing ad-hoc referencing/linking. The link property is for
designating a specify property at a specify place in a structure as
having a value that can be interpreted as a URI for linking purposes.
The hrefProperty designates a single property name, a link attribute can
be used within multiple property definitions (multiple properties on a
single object may denote relationships. For example, you could have
multiple foreign keys that are serialized from a DB row).
> Also, would it make sense to also specify the corresponding
> revProperty (though I noticed they left that out of html5)?
>
It seems like "rev" is becoming increasingly considered poor form, so I
didn't think it would be important to explicitly include it, although
maybe I am getting the wrong impression. It should be noted though, that
using the implicit relationships suggested by the hierarchy of JSON in
combination with partial representations within a href object, one could
define a reverse relationship. For example if had a schema defining the
JSON referencing convention:
{
"hrefProperty": "$ref",
"properties": {
"id": {
"link": "self"
}
}
}
You could imply a reverse relationship in the partial representation:
{
"id": "kris",
"child": {
"$ref": "jennika",
"parent": {"$ref": "kris"}
}
}
Such a structure essentially indicates that the "kris" resource has a
"child" relationship to the "jennika" resource, and a reverse
relationship of "parent" to the "jennika" resource.
> There are a lot of other properties that have hypertextual
> semantics -- I could certainly see the benefit of a titleProperty
> (for accessibility at least).
>
It seems like this would be more important in a format like HTML that
has a more specific visual representation than a data-focused format
like JSON that is more open-ended to being rendered by different views.
But still, that may be a good idea anyway. Especially since it is more
informative, and doesn't really have any behavior requirements that
would add any extra processing requirements on the user agents.
> What about an idProperty and/or nameProperty (for fragments in
> particular), or is all this overkill? Or am I just totally missing
> the mark on the intent of "link"?
>
>
Perhaps, although the JSON schema already has the "identity" attribute
(and of course you can define "link":"self" for a property as well).
>
> Just to bludgeon this dead horse, it may be worthwhile to point out
> the link types spec (more accurately, the semantics of the rel
> property) per html4 [1]
>
> First the spec defines the rules (whitespace as separator, case
> insensitive, extensible, extensible via profile -- which is kinda
> interesting), then it codifies a number of commonly used link types
> and their interpretations. For instance, "alternate":
>
> Designates substitute versions for the document in which the link
> occurs. When used together with the *lang* attribute, it implies a
> translated version of the document. When used together with the
> *media* attribute, it implies a version designed for a different
> medium (or media).
>
> Is there any plan to codify common relationships in JSON Hyper Schema?
> Would it be good enough to use just what's in the html spec? I could
> see the benefit of the "stylesheet" type should someone ever define
> jss (JSON Stylesheet, err, application/style+json: there are a few
> yaml or yaml-like css interpretations floating around, I could imagine
> a json serialization being a useful means for markup, first via a
> client script but eventually perhaps with user-agent support, a la
> xml). Looking down the list, they all look like they may have their place.
It does seem attractive to have relationships between resources maintain
the same meaning across all the different representations of those
resources, but at the same time I wouldn't want to be limited by this
set of relationships.
>
> One quibble I've always had with the above-referenced list (or, with
> html in general) is the lack of explicit transclusion support. The
> distinction between a transclusion and other types of references is
> fairly important, perhaps moreso when it comes to json. It would be
> useful to formalize this relationship type.
Good question. In my implementation work, I have always treated links as
transclusions within the reconstructed object graph. However, once again
the difference between HTML as a visually focused representation and
JSON as a data focused representation seems significant. IMO, it makes
less sense to dictate whether links are transclusions or not in JSON
since the user agent/JSON receiver should have the freedom to be able to
decide if it will treat the links as transclusions (whereas in HTML the
representation wants much more control of how links are to be rendered).
Dictating transclusions might also cause some complexity in determining
at which level in the application the transclusion replacement should
take place (in the object mapping layer or the templating, for example).
Thanks,
Kris
Kris Zyp
Unreserved characters can be escaped without changing the semantics
of the URI, but this should not be done unless the URI is being used
in a context that does not allow the unescaped character to appear.
It seems like we would be violating this RFC if we had #foo%2Ebar%2Ebaz
and #foo%2Ebar.baz resolve to different entities, wouldn't we? Or is it
all right to do this anyway (certainly seems easier)?
--
Kris Zyp
SitePen
(503) 806-1841
http://sitepen.com
Dean Landolt
Via section 4.1 of rfc 2396 (emphasis mine):
When a URI reference is used to perform a retrieval action on theI understand what you're saying, but the semantics of a fragment is the user agent's problem. The "." ought to be able to be escaped one way or another -- frankly I don't care how -- but if we stick with a standard encoding scheme that works the implementors' lives should be a little easier.
identified resource, the optional fragment identifier, separated from
the URI by a crosshatch ("#") character, consists of additional
reference information to be interpreted by the user agent after the
retrieval action has been successfully completed. As such, it is not
part of a URI, but is often used in conjunction with a URI.
Dean Landolt
Clever. But where are the semantics of "parent" defined? Or is it just implied because the $ref points to the parent object?
> There are a lot of other properties that have hypertextual> semantics -- I could certainly see the benefit of a titlePropertyIt seems like this would be more important in a format like HTML that
> (for accessibility at least).
>
has a more specific visual representation than a data-focused format
like JSON that is more open-ended to being rendered by different views.
But still, that may be a good idea anyway. Especially since it is more
informative, and doesn't really have any behavior requirements that
would add any extra processing requirements on the user agents.
Granted JSON's primary use isn't visual representation, but more and more JSON is used as the basis to drive visual elements (e.g. dijits). Providing a means for accessibility hinting like title may be useful.
> What about an idProperty and/or nameProperty (for fragments in> particular), or is all this overkill? Or am I just totally missingPerhaps, although the JSON schema already has the "identity" attribute
> the mark on the intent of "link"?
>
>
(and of course you can define "link":"self" for a property as well).
I'm still unsure what "link": "self" means exactly. I guess more than that, I still can't fully wrap my head around link in general -- I assume it's corralary is HTML's LINK tag, but the mapping seems to break down there. Perhaps I shouldn't try to force an arbitrary mapping to html in my mental model, but could you expound a little more on what's similar and or different about your idea of link vs. HTML?
>> Just to bludgeon this dead horse, it may be worthwhile to point outIt does seem attractive to have relationships between resources maintain
> the link types spec (more accurately, the semantics of the rel
> property) per html4 [1]
>
> First the spec defines the rules (whitespace as separator, case
> insensitive, extensible, extensible via profile -- which is kinda
> interesting), then it codifies a number of commonly used link types
> and their interpretations. For instance, "alternate":
>
> Designates substitute versions for the document in which the link
> occurs. When used together with the *lang* attribute, it implies a
> translated version of the document. When used together with the
> *media* attribute, it implies a version designed for a different
> medium (or media).
>
> Is there any plan to codify common relationships in JSON Hyper Schema?
> Would it be good enough to use just what's in the html spec? I could
> see the benefit of the "stylesheet" type should someone ever define
> jss (JSON Stylesheet, err, application/style+json: there are a few
> yaml or yaml-like css interpretations floating around, I could imagine
> a json serialization being a useful means for markup, first via a
> client script but eventually perhaps with user-agent support, a la
> xml). Looking down the list, they all look like they may have their place.
the same meaning across all the different representations of those
resources, but at the same time I wouldn't want to be limited by this
set of relationships.
It's a codified set, sure, but a non-exclusive set that can be (and is regularly) extended. I understand the concern -- and absolutely this kind of list should probably be in non-normative language (if included at all).
Better still, it would be great to have a way to define and formally standardize on "rel" options for hyperjson (or HTML for that matter) -- there are plenty more useful and oft-used rels (e.g. "nofollow") but it's all pretty ad hoc. Of course this standard probably isn't the place to hash that out.
> One quibble I've always had with the above-referenced list (or, withGood question. In my implementation work, I have always treated links as
> html in general) is the lack of explicit transclusion support. The
> distinction between a transclusion and other types of references is
> fairly important, perhaps moreso when it comes to json. It would be
> useful to formalize this relationship type.
transclusions within the reconstructed object graph. However, once again
the difference between HTML as a visually focused representation and
JSON as a data focused representation seems significant. IMO, it makes
less sense to dictate whether links are transclusions or not in JSON
since the user agent/JSON receiver should have the freedom to be able to
decide if it will treat the links as transclusions (whereas in HTML the
representation wants much more control of how links are to be rendered).
Dictating transclusions might also cause some complexity in determining
at which level in the application the transclusion replacement should
take place (in the object mapping layer or the templating, for example).
Damn. Very true. Still, the idea that casual references to potentially enormous remote JSON objects may result in transclusions troubles me, but this is more an implementation issue.
Kris Zyp
> retrieval action has been successfully completed. *As such, it is not
>
> part of a URI*, but is often used in conjunction with a URI.
>
> I understand what you're saying, but the semantics of a fragment is
> the user agent's problem. The "." ought to be able to be escaped one
> way or another -- frankly I don't care how -- but if we stick with a
> standard encoding scheme that works the implementors' lives should be
> a little easier.
That seems reasonable to me, I certainly agree that URI encoding the "."
in property names would be the easiest path.
Kris Zyp
Dean Landolt wrote:
>
>
> On Thu, Jul 30, 2009 at 4:25 PM, Kris Zyp <kri...@gmail.com
> <mailto:kri...@gmail.com>> wrote:
>
> [snip]
There is no special meaning to "parent" here, just suggesting that the
relationships can be implied from the property names and the JSON hierarchy.
>
> > There are a lot of other properties that have hypertextual
> > semantics -- I could certainly see the benefit of a
> titleProperty
> > (for accessibility at least).
> >
> It seems like this would be more important in a format like HTML that
> has a more specific visual representation than a data-focused format
> like JSON that is more open-ended to being rendered by different
> views.
> But still, that may be a good idea anyway. Especially since it is more
> informative, and doesn't really have any behavior requirements that
> would add any extra processing requirements on the user agents.
>
>
> Granted JSON's primary use isn't visual representation, but more and
> more JSON is used as the basis to drive visual elements (e.g. dijits).
> Providing a means for accessibility hinting like title may be useful.
I would certainly expect that most JSON will ultimately be rendered for
display. The key difference is that HTML is designed to specify
presentation layer information, and JSON is designed to be data-focused,
separated from the presentation layer that would make decisions about
how to render it. But I agree that it seems useful, although I wonder if
it might be better specified in another schema layer.
>
> > What about an idProperty and/or nameProperty (for fragments in
> > particular), or is all this overkill? Or am I just totally
> missing
> > the mark on the intent of "link"?
> >
> >
> Perhaps, although the JSON schema already has the "identity" attribute
> (and of course you can define "link":"self" for a property as well).
>
>
> I'm still unsure what "link": "self" means exactly. I guess more than
> that, I still can't fully wrap my head around link in general -- I
> assume it's corralary is HTML's LINK tag, but the mapping seems to
> break down there. Perhaps I shouldn't try to force an arbitrary
> mapping to html in my mental model, but could you expound a little
> more on what's similar and or different about your idea of link vs. HTML?
I don't think that there is anything wrong with comparing it to HTML's
LINK tag. If you had schema:
{
"properties":{
"alternateRef" : {"link":"alternate"}
}
}
With an instance:
{
"alternateRef": "something_else"
}
This instance would indicate the same relationships the following HTML:
<html>
<head>
<link rel="alternate" href="something_else" />
...
"link":"self" is just an object's reference to itself, for the purpose
of explicitly defining it's canonical URI. The main difference (and
maybe this needs to be clearly articulated in the proposal) is that
individual entities can define their own relationships, and when this
concept is used with "link":"self", it allows for representations other
resources to be embedded in a representation. So if the "id" property
was defined to "link":"self" for everything in an instance, then:
{
"fooProp": {"name":"Foo", "id":"foo"},
"barProp": {"name":"Bar", "id":"bar"},
}
Then the value of the property "fooProp" would the JSON object that is
the full representation of the "foo" resource. That is, the object that
is the value of "fooProp" has defined itself (by using the "self"
relationship) to be the resource located at the "foo" URI. There are two
objects in this structure that have defined their own URI.
It seems these type of things always suggest a need for a registry...
while allowing extensibly, which asymptotically seems to always point to
URIs as the most effective management of distributed definitions while
avoiding naming conflicts. I'm hoping that this could be possible by
making references to canonical JSON schema definitions for
relationships. For example, maybe a schema could do something like:
{
"properties":{
"alternateRef":{"$ref":"http://www.w3.org/schema/rel/alternate"},
...
Where http://www.w3.org/schema/rel/alternate returns:
{"link": "alternate",
"description": "Describe 'alternate' relationship..."
}
So now the link definition has an authoritative URI.
To bring up an important difference between common usage of HTML and
JSON here. With HTML, a transclusion necessitates that the user agent
actually immediately load the referenced link, so it can be rendered
inline. With a typical JSON data usage (at least how we do it in
dojo.data), a object graph transclusion can be handled lazily. The
reference does not need to be loaded until is accessed (or in dojo.data,
until loadItem is called).
Kris
Kris Zyp
http://json-schema.org/draft-hyperschema.txt
* I added a section for JSON forms, which is analogous to HTML forms
(section 3) and provides a way to describe the GET-based querying and
POSTing actions that are available for interacting with a server to
search for and create new resources. This provides better organization
and simplifies the core hyper schema definition which is more strictly
concerned with interpreting links in data, whereas forms are for
querying and creating new documents.
* I noted that an instance may have multiple applicable schemas.
I also had a question on link relations, would it be more appropriate to
reuse some of the link relations from atom:
* Rather than "schema", using "describedby" to describe the relation
from the instance to schema?
* For a link that indicates that the referring object is not the full
representation, but the full representation can be found elsewhere,
would "self", "edit", or something else like "full" be more appropriate?
Thanks,
Kris
Tatu Saloranta
>
...
> I also had a question on link relations, would it be more appropriate to
> reuse some of the link relations from atom:
> * Rather than "schema", using "describedby" to describe the relation
> from the instance to schema?
Yes, I think that would be better wording, even if it wasn't for reuse. :)
(partly because 'schema' might imply there's just one such schema; and
partly since this describes intention, more than how it's achieved).
-+ Tatu +-
KevBurnsJr
- --- -
Last sentence of section 1.4 :
"When collections can heterogenous instances, [...]"
"When collections contain heterogenous instances, [...]"
-
End of paragraph 1, section 2.4.1 :
"If the target is a JSON array, then the target is determined by
[...]"
-
End of paragraph 1, section 2.4.1 :
defined by"
by"
KevBurnsJr
- --- -
Last sentence of section 1.4 :
"When collections can heterogenous instances, [...]"
"When collections contain heterogenous instances, [...]"
-
End of paragraph 1, section 2.4.1 :
"If the target is a JSON array, then the target is determined by
-
End of paragraph 1, section 2.4.1 :
defined by"
by"