search

w3c / json-ld-syntax

JSON-LD 1.1 Specification
https://w3c.github.io/json-ld-syntax/
Other
112 stars 22 forks source link

Consider Infra spec for describing primitive types #199

Closed gkellogg closed 5 years ago

gkellogg commented 5 years ago

@marcoscaceres pointed out the Infra Spec (another What WG product) that exists as a way of describing some fundamental types, such as those we use. Currently, we use a combination of ECMASCRIPT and WebIDL to describe things like strings, numbers, booleans, and objects/dictionaries, which isn't entirely satisfying. Infra might be a better way to go, but would likely require some large changes to the text.

In 1.1 we (I) made a change from describing changes to objects to dictionaries, because JSON objects are serialization artifacts of an internal structure and it doesn't make sense to describe updating them. Also, we were trying to abstract away from JSON for describing API operations.

We're currently updating our terminology (see PR #198) and now might be a time to consider such a change.

Other than changing definition references, Infra uses the concept of a Set and Map (with entries) in deference to our array and dictionary (with members).

iherman commented 5 years ago

I had a cursory look at that document and it mostly looks to me as a stylistic agreement (ie, not some sort of a replacement of WebIDL). Which is perfectly fine, of course, but then whether it is appropriate for our spec or not is entirely an editorial issue. Ie, @gkellogg and @pchampin have, as far as I am concerned, full decision power on this...

dlongley commented 5 years ago

Looking at this... I had an initial concern with how using this other spec's language would be understood in the context of JSON and JavaScript's parse and stringify methods. For example, I wouldn't want an implementer to think "Wait, I can't just call JSON.parse() ... I have to translate the output to Set and Map types in my implementation?" However, it seems that the Infra spec has a section that is explicitly about this -- and it seems to assuage some concern that this is just about being able to describe types in standards independently of realm:

https://infra.spec.whatwg.org/#json

The above two operations operate on JavaScript values directly; in particular, this means that the involved objects or arrays are tied to a particular JavaScript realm. In standards, it is often more convenient to parse JSON into realm-independent maps, lists, strings, booleans, numbers, and nulls.

This makes me more comfortable that there wouldn't be some kind of impedance mismatch or confusion with how implementations work with parsing/serializing JSON and the Infra types. I suspect most could look at the sections that transform a "JSON-derived JavaScript value" to/from an Infra type and make whatever optimizations are appropriate.

gkellogg commented 5 years ago

Actually, we'll want to use List instead of Set. This implies updating the language where we use array to using list as well as updating dictionary to map.

gkellogg commented 5 years ago

Included changes for this in PR #198.

gkellogg commented 5 years ago

Closed via #198, w3c/json-ld-api#116, and https://github.com/w3c/json-ld-framing/commit/ba733715bf92f1498020b20ddc166ad63c23a5f7