Example Generation Adding @Context

[adam-lerner]

In several spots in the Traceability Vocab, I've noticed that examples are being generated with contexts embedded into the credential subject and other properties. These additional contexts are not needed and we should fix the example generator to not display them. See example below for credentialSubject and relatedDocuments:

    "@context": [
      "https://w3id.org/traceability/v1"
    ],
    "type": [
      "BillOfLading"
    ],
    "billOfLadingNumber": "991205182",
    "relatedDocuments": [
      {
        "@context": [
          "https://w3id.org/traceability/v1"
        ],
        "type": [
          "Purchase"
        ],
        "customer": {
          "type": [
            "Person"
          ],
          "email": "[email protected]",
          "phoneNumber": "555-152-7258"
        }
      }
    ],

[OR13]

@mprorock @Therecanbeonlyone1969 @mkhraisha can I assign one of you to fix this?

[OR13]

Synthetic data generation should not nest contexts.

[Therecanbeonlyone1969]

@OR13 ... yeah i can do that together with the suggested enhancements etc.

[mkhraisha]

Happy to take over this, if needed.
my proposal is to modify all generator functions to return based on a flag or to recursively strip context from the final generated object.
I believe the conversion to generators that return a static blob should be done by individual contributors on the vocabulary they contributed to make sure it "makes sense" in business context.

[mkhraisha]

The agreement on the 29/06 call was to remove nested contexts and place them on the root level context object and remove duplicates.

So assuming:

    "@context": [
      "https://w3id.org/traceability/v1"
    ],
    "type": [
      "BillOfLading"
    ],
    "billOfLadingNumber": "991205182",
    "relatedDocuments": [
      {
        "@context": [
          "SECOND CONTEXT"
        ],
        "type": [
          "Purchase"
        ],
        "customer": {
          "type": [
            "Person"
          ],
          "email": "[email protected]",
          "phoneNumber": "555-152-7258"
        }
      }
    ],

this would change to

 "@context": [
      "https://w3id.org/traceability/v1",
          "SECOND CONTEXT"
    ],
    "type": [
      "BillOfLading"
    ],
    "billOfLadingNumber": "991205182",
    "relatedDocuments": [
      {
        
        "type": [
          "Purchase"
        ],
        "customer": {
          "type": [
            "Person"
          ],
          "email": "[email protected]",
          "phoneNumber": "555-152-7258"
        }
      }
    ],
    

[mkhraisha]

@msporny this is probably something you want to weigh in on.

[msporny]

@msporny this is probably something you want to weigh in on.

If the contexts are all duplicated, then moving them all to the top is a good thing. If the contexts are unique, and occur at multiple levels of the document, you may want to think more deeply about the ramifications.

Doing either is fine (keep in place OR migrate to top). If you're going to migrate all contexts to the top level of a document, you may want to use scoped properties to narrow the fields where the second context comes into play. For example, you could scope by type for 'Purchase' -- examples of scoping by type can be found here:

https://github.com/digitalbazaar/ed25519-signature-2020-context/blob/master/contexts/ed25519-signature-2020-v1.jsonld#L11

If you scope by type, you avoid polluging your top-level namespace (a good thing). The downside to moving all contexts to the top level is that if you want to pluck the purchase order out of the relatedDocuments array, you will have to make sure your code migrates the appropriate @context back into the purchase order.

Personally, I'd prefer to keep the second context with the purchase order, but don't know the details of the use case to comment more than that.

relatedDocuments

Minor nit, always use singular form for words to be consistent. All properties in JSON-LD (and graph-based data models in general) can always have one or more values associated with them. So, either all properties should be plural, or all properties should be singular. In general, you will have more singular properties than plural, which is why all properties tend to be singular form. It's not a requirement, but rather a stylistic one (that some people disagree with).

[OR13]

PROPOSAL: replace $comment: string with $linkedData : object

[OR13]

This proposal passed on todays call, I have the action of making these changes available.

[OR13]

PROPOSAL: ask JSON-LD and JSON Schema WGs/teams for help with making JSON-LD Schema (or JSON Schema-LD) a more functional option (see issue #150)

We resolved this proposal as well.

[OR13]

/me PROPOSAL: We will use OAS3.0 YAML Schemas in trace vocab, instead of JSON Schema in JSON

differed to next meeting, pending issues opened and feeback requested.

[OR13]

I have been taking notes here, please excuse my mess, I am moving these to separate issues.

• RESOLVED: replace $comment: string with $linkedData : object #184
• Ask JSON-LD and JSON Schema WGs/teams for help with making JSON-LD Schema #185
• PROPOSAL: We will use OAS3.0 YAML Schemas in trace vocab, instead of JSON Schema in JSON #186