Continuing discussion from transmute-industries/traceability-vocab#2

There are currently some schemas in main that were not submitted with tests, which causes the test suite to fail for any other new schemas. Tests should be added to create the needed test-vectors and/or the schemas should be temporarily removed in order to allow other schemas to be added.
These schemas are in docs/schemas:

• ProductRegistrationEvidenceDocument.json
• VLEIIdentityCredential.json
• LEIevidenceDocument.json

For any term where GS1 just copied schema.org, we should use schema.org definition instead.

For example:

https://www.gs1.org/voc/Place -> https://schema.org/Place

Continuing discussion from transmute-industries/traceability-vocab#3

now that we have some .env requirements I believe a sample .env should be added to allow easier onboarding.

I'm wondering at which point in the described process the test-vectors files are created in the docs folder. Based on the readme, in order to properly contribute, the developer needs to create a JSON schema, create a synthetic data gen file, and run the tests. Is this when the build happens to create the test-vectors file for the new vocab or is there a separate call that isn't listed?
I've attempted to run the process with the simplest file I could create and it always fails due to the docs/test-vectors file having not been generated.

Continuing discussion from transmute-industries/traceability-vocab#4

need to account for agricultural labeling requirements with an AgProduct that extends Product - should account for the FDA labeling requirements data at the crate level found here: https://www.producetraceability.org/documents/FINAL_PTI_Harmonized_Traceabilty_Case_Label_April_2020_(003).pdf

We need a way to bypass generation of JSON-LD and provide manual test vectors and examples. This will aid in resolution of #89 #88

@Therecanbeonlyone1969 - I know this is time sensitive for your team. Will try and get this in and documented tonight.

Can we agree that everything can be utf-8?

We'd like to add @mprorock and myself (from Mesur.io) to the editors section #23

Multiple IRIs that should resolve properly, to a proper definition are being routed improperly. A pretty big PR to correct this so that there are solid examples rolling forward is incoming. This PR will be merged quickly to resolve breakages

We need to be able to define and later on identify a legal entity within the traceability schema to be able to ensure that certain VCs are only issued by legal entities.

Key questions to answer:

• How do we represent an entity (within a supply chain for example)?

• How can we represent a legal entity vs just an entity? Can they be connected?

• How do we distinguish between different government/legal definitions of a legal entity within the traceability vocab?

For Reference & Further Discussion:

From Schema.org:

Legal entity identifier -> see also links to GLEIF in this link
https://schema.org/leiCode

Definition of organization from schema.org:
https://schema.org/Organization

GLEIF LEI framework:
https://www.gleif.org/en/about-lei/introducing-the-legal-entity-identifier-lei#

IS) 17442 -- Legal Entity in Financial Services:
Part 1:
https://www.iso.org/standard/78829.html

Part 2:
https://www.iso.org/standard/79917.html

Have you looked at the UBL 2.2. specification for the 80+ most common business documents:
http://docs.oasis-open.org/ubl/os-UBL-2.2/UBL-2.2.html#S-UBL-2.2-DOCUMENT-SCHEMAS

All IRIs should read to human readable documentation that is not a PDF (anchors or webpages, not pdfs).

I'm wondering what the suggested and/or required processes are for testing and validating code prior to merging? Has this been established yet or is it TBD?

perma-id/w3id.org#1891

We are creating confusion by defining credential... we should instead define "TraceabilityCredential" or similar... VC Data Model is responsible for defining Verifiable Credentials... not us

      "sellByDate": "10-3-2021"

I don't understand how changing dates falls under fixing IRIs ... but as long as you're fixing dates, please let's use ISO standard YYYY-MM-DD across the board! (Is the above meant to say March 10, i.e., is it DD-MM-YYYY, or October 3, i.e., is it MM-DD-YYYY?)

Originally posted by @TallTed in #81 (comment)

Opening a new issue, per @OR13's request.

@mprorock cited the README:

Wherever possible, dates should be formatted as YYYY-MM-DD so as to be directly compatible with xsd:date.

• https://service.unece.org/trade/uncefact/vocabulary/uncefact/
• https://edi3.org/specs/edi3-json-ld-ndr/main/#json-ld

We may want to support it, but we need to comprehend how it relates to EPCIS, GS1, and other vocabs.

This question is more for clarification than anything else, but I wanted to make sure I was clear before getting too far...
In most of the existing schemas, the properties will be defined this way:

"identifier": {
      "$comment": "{\"term\": \"identifier\", \"@id\": \"https://schema.org/identifier\"}",
      "title": "Property Identifier",
      "description": "Identifiers for a property.",
      "type": "string"
},

The @id references the schema entry for GeoCoordinates and it's basically exactly what's defined in schema.org.
As I'm building out larger schemas, there might be multiple identifiers (for example) in the same schema. This will of course cause issues because you can't have two identical @id's in the same schema. Also, given there are two identifier types in the same schema there is some sort of differentiation there that should be captured.
This problem is especially relevant in having multiple places in the same schema (post of entry vs. foreign port export, for example)
All that to say, what I've done in an upcoming PR is to have the IDs reference the schema they're in and use @type to point to the schema type. Like this (in a ppq203.json schema):

"certificateNumber": {
            "$comment": "{\"term\": \"certificateNumber\", \"@id\": \"https://w3id.org/traceability/schemas/ppq203.json#certificateNumber\", \"@type\": \"https://schema.org/identifier\"}",

...

},
        "carrierId": {
            "$comment": "{\"term\": \"carrierId\", \"@id\": \"https://w3id.org/traceability/schemas/ppq203.json#carrierId\", \"@type\": \"https://schema.org/identifier\"}",

...

},

Does this make sense as a proper way to define properties moving forward that are of a certain type but have a more specific definition in the schema?
@OR13 @mprorock @mkhraisha

not a huge amount security related with this repo as it is vocabulary, but we at least need the existing section to have details that for security related topics, the ccg security vocab should be used and/or NIST specs as approriate. no need to reinvent the wheel on things that already exist.

@OR13 would you be able to write something quick up that can be added to later? Privacy is related, and needs a similar update

alpha numeric / filer code / entry number + check digit

After creating a new schema, following the steps, and running the tests, the tests fail and are expecting a file in the docs/test-vectors directory. Does this file need to be created manually the first time? How does the initial generation run?
Thanks
@OR13 @mprorock

Is there any objection to using a separate context that overlaps very little or not at all with that of the materials-tracking use-cases? Since there is so much semantic alignment happening in other venues on logistics, international shipping and trade, we would ideally like to focus our interoperability in that direction. My colleague Burkhard will be opening an issue later this week with input documents or links about that alignment, but I figured I should make a procedural issue first in case we were barking up the wrong tree.

@Therecanbeonlyone1969
There is a trick to this that i used in IntentToSell

effectively in the comment section where you are defining the @ id you have to have a unique value as it uses a struct to map over when building the json-ld from the schema, the easy way to do this is to add a query param that is meaningless, but unique within the object (similar to cache busting)

edit:

"seller": {
            "$comment": "{\"term\": \"seller\", \"@id\": \"https://w3id.org/traceability?1#Entity\"}",
            "title": "Seller",
            "description": "Entity that is declaring their intention for a product to be used at a different location than where it was created.",
            "$ref": "https://w3id.org/traceability/schemas/Entity.json"
        },
        "purchaser": {
            "$comment": "{\"term\": \"purchaser\", \"@id\": \"https://w3id.org/traceability?2#Entity\"}",
            "title": "Purchaser",
            "description": "Entity that is expected to receive some amount of the product, though possibly a reseller.",
            "$ref": "https://w3id.org/traceability/schemas/Entity.json"
        },

note the ?1 and ?2 in seller and purchaser, even though both resolve to Entity

I have validated this on the json-ld org's playground as well. Big thing to be aware of is making sure you are using a query string that isgoing to be ignored by the hosting page, and in the case of stuff resolving to w3id.org (or other gh pages stuff like it), make sure the query string comes before the hash

Originally posted by @mprorock in #79 (comment)

Continuing discussion from: transmute-industries/traceability-vocab#1

We should establish a max JSON Document size.

The schema referenced below does not resolve and check properly in the js-vc-ci-tests. I need to have the following context array in the test generator file for the EcommercePackingListRegistrationCredential for the test to pass.

[
        'https://www.w3.org/2018/credentials/v1',
        'https://w3id.org/traceability/v1',
        { "orderNumber": "https://schema.org/orderNumber" },
        { "productInOrder": "https://schema.orgproductID" }
    ]

It tells me that "orderNumber" and "productInOrder" are not defined in the context.

Even though I have

"EcommercePackingListRegistrationCredential": {
      "@id": "https://w3id.org/traceability#EcommercePackingListRegistrationCredential",
      "@context": {
        "packageItems": {
          "@id": "https://schema.org/ItemList"
        },
        "certificateName": {
          "@id": "https://schema.org/name"
        }
      }
    }

in the traceability context file.

Note that in the schema for the EcommercePackingListRegistrationCredential, packageItems is of the type array where each array entry MUST is a list "orderNumber" and "productInOrder", where "productInOrder" is an array itself.

{
    "$id": "https://w3id.org/traceability/schemas/EcommercePackingListRegistrationCredential.json",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$comment": "{\"term\": \"EcommercePackingListRegistrationCredential\", \"@id\": \"https://w3id.org/traceability#EcommercePackingListRegistrationCredential\"}",
    "title": "EcommercePackingListRegistrationCredential",
    "description": "Ecommerce Packing List Registration Credential",
    "type": "object",
    "required": [
        "@context",
        "packageItems",
        "certificateName"
    ],
    "properties": {
        "@context": {
            "type": "array"
        },
        "type": {
            "oneOf": [
                {
                    "type": "string"
                },
                {
                    "type": "array"
                }
            ]
        },
        "packageItems": {
            "$comment": "{\"term\": \"packageItems\", \"@id\": \"https://schema.org/ItemList\"}",
            "title": "packageItems",
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "orderNumber": {
                        "$comment": "{\"term\": \"orderNumber\", \"@id\": \"https://schema.org/orderNumber\"}",
                        "title": "orderNumber",
                        "description": "The seller specific Order VC ID",
                        "type": "string"
                    },
                    "productInOrder": {
                        "$comment": "{\"term\": \"productInOrder\", \"@id\": \"https://schema.org/productID\"}",
                        "title": "productInOrder",
                        "description": "Product VC IDs included in the order",
                        "type": "array"
                    }
                }
            }
        },
        "certificateName": {
            "$comment": "{\"term\": \"certificateName\", \"@id\": \"https://schema.org/name\"}",
            "title": "certificateName",
            "description": "Specific name of issued packing list registration certificate",
            "type": "string"
        }
    },
    "additionalProperties": false,
    "examples": []
}

Also, note that this error does not appear when I run the schema tests where the schema test generator is basically identical to the credential test generator.

cc @OR13

https://www.jsonld-checker.com/?tab=2&repo=https%3A%2F%2Fgithub.com%2Fw3c-ccg%2Ftraceability-vocab

per #34

In creating new schemas for the AgInspectionReport, I noticed that in the current repo, we have schemas that are not modified or extended (as far as I can tell) from the ones they reference on GS1 or schema.org. Why is that? Shouldn't we simply ref out to Place, for example, rather than having it in the repo?

Need to add some sections regarding shipping / arrival data modeling.

we need that ability to declare simply that there is a product that an organization intends to sell into some other destination country than the origin country. This is not as complex as a product registration, but a very simple Org that will be exporting, target country to sell to, and the item that is intended for export.

We would to have confidence that the schemas and contexts and spec are all "passing" on every PR.

We would also like to have code that generates synthetic data that allows those tests to pass.

This issue is to discuss how to structure this using javascript in this repo.

This repo should have a clear an consistent pr and merge policy agreed upon by the editors.

I would propose at a minimum a first review for a PR should go in within 24hrs of the PR being submitted by one of the editors.

If the changes are non breaking, limited in scope, etc then a single approval should be sufficient to merge after a 24hr delay unless an editor requests more time. This should also apply to documentation updates that do not change project policy, release schedules, etc. that would affect the entire project.

If there is an impact beyond a single supply chain use case (as limited by commodity - e.g. steel, oil, gas) or by a cross use-case common supply chain tracking events or requirements, then more time should be automatically allocated for review prior to merge, and merge should require a majority vote (or possibly consensus?).

As we are cherry picking into releases based on stability and test passing, and in addition, keeping track of backwards compatibility issues this kind of merge policy should work well.

Requesting input from the editors: @OR13 and @mkhraisha

Very open on this topic, but it seems like we will head off future community issues by clearly stating this policy and tying it back to the contribution requirements. once we are agreed on a policy, (and it can be very simple). I will doc that up and submit a PR with the document updates.

We've been exploring the possibility of pulling these schemas and test vectors programmatically to validate and use as models in our app. In order to do this safely it would make sense to have versioning on this repo. Any thoughts/concerns/etc. on doing this?

#45 (review)

https://github.com/w3c-ccg/vc-status-list-2021

we should set some default max lengths for strings.

When running the tests on new schemas, there are often confusing errors due to the link that is populated for @id in the $comment on properties. I realize that this id should simply be a link to a human readable page explaining the property itself. So, I'm confused why often the link causes the linked data conformance test (linked-data-conformance.test.js) to throw an error. Here is a simple example. When I run the test on AgProduct with this code as the property value:

        "product": {
            "$comment": "{\"term\": \"product\", \"@id\": \"https://schema.org/Product\"}",
            "title": "Product",
            "description": "Product details as specified in the Product.json schema",
            "$ref": "https://w3id.org/traceability/schemas/Product.json"
        }

I get the follow error when running that test: { type: 'MISSING_PROPERTIES_IN_CONTEXT', details: '["product"]' }
However, when I run it with this code pointing to GS1:

        "product": {
            "$comment": "{\"term\": \"product\", \"@id\": \"https://www.gs1.org/voc/Product\"}",
            "title": "Product",
            "description": "Product details as specified in the Product.json schema",
            "$ref": "https://w3id.org/traceability/schemas/Product.json"
        }

the tests pass.
I'm confused as to why this is, partially because of this specific case of schema vs. gs1, but mostly because I'm wondering why the test is strict on ID which is something that I thought was meant to be mostly for humans and not machine readable.
Thanks.

Proposal

1. make all synthetic data generation deterministic (no randomness)
2. add a github action to commit updates to the docs folder on merges
3. add .gitkeep and build steps to postinstall so that tests pass on first clone

Previous description

Faker data is working generally great for this, but we need a way to pin certain items that change based on random keys - e.g. dates. Right now someone contributing to the repo cannot do so by only adding schema, test vectors, and credentials related to the object they are adding and have tests pass.

We need to spend a bit of time on the test and build process and establish some good docs and policies on this. I welcome thoughts from @OR13 and @brianwmunz as well as @mkhraisha especially.

Floating point number precision for CMTR fields should be 4 decimal places?

How is the traceability vocab related to SAP?

How is the traceability vocab related to Mulesoft?

we should set some default max lengths for strings.

max length for data uris, no image urls.

One helpful premise for aligning our use-cases for SC-specific test scenarios and user stories would be distinguishing process VCs (batch-specific, tied to specific import shipments) and non-process VCs (product definitions, legal entity verifications/enrolments, mappings of products to HTS codes, UPC codes, GTINs, etc). This has been very important in our use case, where there is a 1-to-many relationship between non-process VCs to shipments.

I've created a schema for an Inspection Report that is specific for agriculture inspection, using the InspectionReport schema as a foundation. I'll submit a PR for review (@mprorock and @OR13 ) once I get permission to create a branch or I'll just fork it.

Update the current section to provide insight and information on the work that is currently being covered, with the entities that are focused on those areas filling in more details.

Proposed starting point for the language:

This section is non-normative.

The following use cases outline a number of key scenarios that readers might find useful:

• Supply Chain Traceability of Steel
• Supply Chain Traceability of Oil
• Supply Chain Traceability of Food
• Supply Chain Traceability of Natural Gas
• Supply Chain Traceability of Direct-to-Consumer E-Commerce Shipments

max length for data uris, no image urls.

A friendly suggestion...

For the following classes:

• PostalAddress
• Place
• GeoCoordinates

and attributes within those classes, please consider referencing schema.org URIs for those where they exist, instead of referencing the corresponding terms within the GS1 Web vocabulary.

GS1 Web vocabulary ( https://www.gs1.org/voc ) is positioned / acknowledged as an external extension to schema.org and provides a richer set of terms for describing products in greater detail. However, for Organization, Place, PostalAddress and GeoCoordinates we basically replicated most of what was in those schema.org classes without really adding much new, so it's much fairer to reference schema.org for those, even though other Linked Data ontologies (e.g. vCard ) provided some of those terms even earlier.