Remove @omitDefault?

[gkellogg]

The @omitDefault flag can be added to a frame to change the default value for the omit default flag, which might be set to true through an API call. This keyword is of dubious value, since the frame can simply add @default at all.

Propose removing the keyword. We may also want to consider how important the runtime flag is.

[dlongley]

I think the @omitDefault flag was added to enable the granular prevention of properties (that need to have other flags set on them) from appearing in the output when they aren't present in the data.

An example is here: https://github.com/digitalbazaar/jsonld.js/issues/117

Though, sadly, the playground example is now partially broken because the user's context went away. But the basic idea there was that some property needed to be marked with "@embed": "@never" but, if that property was not present in the data, it needed to be omitted entirely in the output... regardless of whether default values were permitted elsewhere.

[iherman]

This issue was discussed in a meeting.

• ACTION: provide example in issue frame/41 of @omitdefault need (Dave Longley)
  View the transcript

  Remove @omitdefault
  Rob Sanderson: link: https://github.com/w3c/json-ld-framing/issues/41
  Gregg Kellogg: also: https://github.com/w3c/json-ld-framing/issues/46
  Rob Sanderson: The first issue we discussed briefly last call before we realized we needed to talk a bit more about it.
  Gregg Kellogg: Another issue is to provide a better example for its use.
  … Of @omitDefault.
  … The issue is suggesting that @omitDefault is not particularly useful when you can just omit when using default. I think Dave had alluded to some examples where it was useful and that’s why there’s an issue open to highlight where it’s actually useful.
  … Otherwise we could remove it from the spec.
  … The only way to make a default is to use @default.
  Dave Longley: There’s a few ways to have a default. There’s an interaction with explicit. A default of null, if the property is specified but not present. Then output has a default value of null
  … sometimes you don’t want it with a value of null, but instead absent.
  … Also, if you had specified a default, and some other properties to have flags on them.
  … a case would be when you say ‘foo’ and you want to embed:always for foo.
  … [example]
  Gregg Kellogg: Ok, I think you’ve made a case for why it needs to be there. Having implemented it I still don’t understand the need for it. As long as you take on the responsibility of better documenting the use of @omitDefault.
  … If you can provide an example so we can adequately spec it that would be sufficient.
  Action #1: provide example in issue frame/41 of @omitdefault need (Dave Longley)
  

[dlongley]

Here's an example of where @omitDefault is useful:

Suppose the following input:

{
  "@context": {
    "@vocab": "http://example.org/",
    "child": {"@type": "@id"}
  },
  "@graph": [
    {
      "@id": "http://example.org#John",
      "@type": "Person",
      "name": "John",
      "child": "http://example.org#Jane"
    },
    {
      "@id": "http://example.org#Jane",
      "@type": "Person",
      "name": "Jane"
    }
  ]
}

Suppose this frame (that does not have @omitDefault):

{
  "@context": {
    "@vocab": "http://example.org/",
    "child": {"@type": "@id"}
  },
  "@type": "Person",
  "child": {
    "@embed": "@always"
  }
}

This is the framed output:

{
  "@context": {
    "@vocab": "http://example.org/",
    "child": {
      "@type": "@id"
    }
  },
  "@graph": [
    {
      "@id": "http://example.org#Jane",
      "@type": "Person",
      "child": null,
      "name": "Jane"
    },
    {
      "@id": "http://example.org#John",
      "@type": "Person",
      "child": {
        "@id": "http://example.org#Jane",
        "@type": "Person",
        "name": "Jane"
      },
      "name": "John"
    }
  ]
}

Note that because the option "@embed": "@always" is specified in the frame under the child property, that "child": null appears in the output for matches that do not have that property. This may be undesirable. To prevent this default null output from occurring, the @omitDefault may be set to true like so:

{
  "@context": {
    "@vocab": "http://example.org/",
    "child": {"@type": "@id"}
  },
  "@type": "Person",
  "child": {
    "@embed": "@always",
    "@omitDefault": true
  }
}

Which yields this (desirable) output:

{
  "@context": {
    "@vocab": "http://example.org/",
    "child": {
      "@type": "@id"
    }
  },
  "@graph": [
    {
      "@id": "http://example.org#Jane",
      "@type": "Person",
      "name": "Jane"
    },
    {
      "@id": "http://example.org#John",
      "@type": "Person",
      "child": {
        "@id": "http://example.org#Jane",
        "@type": "Person",
        "name": "Jane"
      },
      "name": "John"
    }
  ]
}