@omitDefault behavior

[serwan]

Hi,
We are using @omitDefault flag to get clean output with framing process.
When I read the framing spec/algo I understand that It can be put on the root of the frame and has impact on the subtree. (same behavior than @explicit)
When I use the official playground putting @omitDefault on the root of the frame has no impact.
Am I misunderstanding the spec ?
Serwan

[dlongley]

The framing spec needs to be more clear on this point (and it hasn't been updated in a while).

Because default values will only be added to explicitly listed properties in the frame, you must also explicitly list @omitDefault in the subframes associated with those properties. As an alternative, you can pass omitDefault: true as an option to the framing API itself, to override the default so that if @omitDefault is not specified in your frame, it will be assumed to be true.

So, to explain what's going on, look at this frame:

{
  "@context": "...",
  "someProperty": {}
}

When someProperty is processed during framing, it has an empty subframe {} that was specified with it. Since there is no @omitDefault flag in that frame, whatever the API is configured to use as the default value will be used for that flag. If you don't set it in the API options, then it will be false. Note that this behavior is actually the same for other flags, like @explicit, as well -- whenever a subframe is specified in your frame, it will follow this behavior. Only when a subframe is implicitly created during processing, will the flags will propagate.

Implicit subframes are only generated when a processing rule calls for a subframe and one wasn't given by the frame author. This occurs when recursing into embedded nodes.

[serwan]

Ok, that's clear,
omitDefault: false is the default value,
you can change this with the API,
you can specify in the frame with @omitDefault: true/false the behavior, which can propagate on subframe.

With this frame :

{
  "@context": "...",
  "@omitDefault": true,
  "@explicit": true,
  "someProperty": {},
  "someMissingProperty": {},
}

And this input :

{
  "@context": "...",
  "someProperty": "value1",
  "anotherProperty":  "value2"
}

Should result as :

{
  "@context": "...",
  "someProperty": "value1"
}

I'm actualy working on a implemantation/tests with a fork of https://github.com/lanthaler/JsonLD, which can be found here : https://github.com/conjecto/JsonLD

[dlongley]

Actually, the result would empty per the current algorithm, because you're using a duck-type query instead of a strict @type query. A strict @type query doesn't require all properties to be there, just the @type to match. For duck-type queries, all properties must be present unless you do something like this in your frame:

{
  "@context": "...",
  "inputMustHaveThis": {},
  "notRequired": {"@default": "unused", "@omitDefault": true}
}

But that seems a bit like an abuse of duck-typing and we may want something cleaner in the future if this is a common use case for duck-typing. Currently a typical duck-typing use case is to find nodes that actually have all of the properties you're looking for; if they don't, they don't come back in the response. So if you don't require a particular property, simply omit it in the frame. If you do require it, but it may not be there, set a @default. Setting a @default and then omitting it with @omitDefault is strange.

I'm actualy working on a implemantation/tests...

Since you're working on updating a framing implementation, I recommend looking at these for the latest algorithm (as the spec is very outdated):

Python: https://github.com/digitalbazaar/pyld/blob/master/lib/pyld/jsonld.py
PHP: https://github.com/digitalbazaar/php-json-ld/blob/master/jsonld.php
JavaScript: https://github.com/digitalbazaar/jsonld.js/blob/master/js/jsonld.js

You'll find implementations for things like @link in there as well (see #377).

[serwan]

Ok, then duck-type query/frame with @explicit: true filter the resource with the property set specifyed in the frame.

And typed query/frame with @explicit: true filter the property of the resource (with the property set specifyed in the frame too)

Then if I unduck-type the process :

With this frame :

{
  "@context": "...",
  "@omitDefault": true,
  "@explicit": true,
  "@type": "t1",
  "someProperty": {},
  "someMissingProperty": {},
}

And this input :

{
  "@context": "...",
  "@type": "t1",
  "someProperty": "value1",
  "anotherProperty":  "value2"
}

Should result as :

{
  "@context": "...",
  "@type": "t1",
  "someProperty": "value1"
}

[dlongley]

If you want to omit the default value for someMissingProperty, then you must do this in your frame:

{
  "@context": "...",
  "@explicit": true,
  "@type": "t1",
  "someProperty": {},
  "someMissingProperty": {"@omitDefault": true}
}

Note @omitDefault is in the specified subframe for someMissingProperty, not at the top-level. Whenever you specify a subframe (even if it's an empty one: {}), it will use whatever flags are in that subframe, and if a flag isn't specified, it will use the flag value given to the API ... and the flag wasn't given to the API, it will use the spec default. So, because the subframe is specified in the frame, and not implicitly created, it won't use any @omitDefault value from the top-level (or from some other parent level in the tree).

So the algorithm does this on this input:

{
  "@context": "...",
  "@omitDefault": true,
  "@explicit": true,
  "@type": "t1",
  "someProperty": {},
  "someMissingProperty": {}
}

1. Notice that someMissingProperty has a subframe specified, it is the empty subframe: {}.
2. When checking for @omitDefault, check the specified subframe first. It's not there.
3. Since it's not there, check the API options. If no value for omitDefault was given in the options, use the spec default, which is false.

When this same algorithm operates on the frame I provided at the top of this comment, it will find @omitDefault in the subframe and set it to true, producing the output you specified.

[dlongley]

I made some edits to my previous comment, make sure you see those for clarification.