added removing 'type' field in dimensions and reportingStandard

[karinaliauw]

What type of PR is this? (check all applicable)

• 🍕 Feature
• 🐛 Bug Fix
• 📝 Documentation Update
• 🎨 Style
• 🧑‍💻 Code Refactor
• 🔥 Performance Improvements
• ✅ Test
• 🤖 Build
• 🔁 CI
• 📦 Chore (Release)
• ⏩ Revert

Description

Related Tickets & Documents

Mobile & Desktop Screenshots/Recordings

Added tests?

• 👍 yes
• 🙅 no, because they aren't needed
• 🙋 no, because I need help

Added to documentation?

• 📖 Mock App docs site
• 📜 README.md
• 📕 storybook
• 🙅 no documentation needed

[optional] Are there any post-deployment tasks we need to perform?

[gemini-code-assist]

Summary of Changes

Hello @karinaliauw, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request updates the v0.6.0 migration guide to accurately reflect recent schema changes. The primary focus is on documenting the simplification of data models by removing the type field from the issuingParty within emissionsScorecard.reportingStandard and from the Dimensions structure. Additionally, it refines existing documentation regarding the simplification of issuingParty in referenceStandard and administeredBy in Regulation by removing the nested idScheme structure.

Highlights

• Documentation Update: The v0.6.0 migration guide has been updated to reflect recent schema simplifications.
• Schema Simplification: The documentation now explicitly states the removal of the type field from the issuingParty within the emissionsScorecard.reportingStandard structure.
• Schema Simplification: The removal of the type field from the Dimensions structure has been documented.
• Documentation Refinement: Existing documentation for issuingParty in referenceStandard and administeredBy in Regulation has been corrected to accurately describe the removal of the nested idScheme structure.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request updates the v0.6.0 migration guide to document the removal of the type field from Dimensions and reportingStandard. While reviewing, I found a minor typo and a couple of inconsistencies in the documentation that need to be addressed.

1. There's a typo in emmissionsScorecard.
2. The After (0.6.0) example for reportingStandard.issuingParty incorrectly includes an idScheme, which is inconsistent with the schema and other examples.
3. The documentation states that the type field is removed from Dimensions, but the provided v0.6.0 schema still contains it.

Please see the detailed comments for suggestions.

[gemini-code-assist]

This change states that the type field is removed from the Dimensions structure, and the example at lines 1807-1868 reflects this. However, this contradicts the schema in packages/untp-test-suite/src/schemas/digitalProductPassport/v0.6.0/schema.json, where the Dimension definition (lines 553-597) still includes the type property. Please synchronize the documentation and the schema. If the schema is correct, this documentation change should be reverted.

[ashleythedeveloper]

The type property should be removed from the Dimensions object, as I believe it’s an unintended artefact generated by Jargon when producing the DPP Schema. @absoludity, can you shed any light on this?

[absoludity]

Sorry, I don't remember any of the context here - can you provide a little more? I don't remember type being an unintended artefact, but I do remember that jsonld interpreters don't require you to set it iff the related context file makes it clear what type a property has. I'm happy to spend some time playing with Jargon to understand, but I also need more context here about what I'm looking for (eg. why is it an issue to specify the type or not - is it causing an error?)

[ashleythedeveloper]

Jargon is adding types within the schemas where they're not needed, in this case "type": "Dimensions" in the DPP schema.

When developers construct credentials conforming to the respective UNTP schema, they inadvertently add the types, issue credentials and then attempt to validate the credentials with the tooling we provided them.

They are then faced with a relative type reference error. This issue is common throughout the JSON schemas of the UNTP data models.

dpp-dimensions-example.json

[absoludity]

So I think that maybe the issue is around the other way: The schema should indicate that the "type" for the Dimension entity can be present (it should be a possible to define the "type" on any entity, it's just not always required if the context already tells you what the entity at a given path is).

But yes, the schema has it as required (https://test.uncefact.org/vocabulary/untp/dpp/untp-dpp-schema-0.6.0.json ), so we should include it. The real problem is, IMO, that the context file isn't defining Dimension, but maybe there's a way to stop the type being required in the schema? Best check with Alistair.

Detail

If you look at other entities, such as Claim, you'll see it's defined in the context linked from the dpp example you have, but Dimension isn't. That's the cause of the error: the parser understands that the entity is something called a Dimension, but nothing in the context defines what that is (unlike other entities).

Now the reason Dimension is not defined in the context, is, I think, because it's a "Green" entity in Jargon (that is, an entity which doesn't have a unique identifier). You can read more at https://docs.jargon.sh/#/pages/language?id=identifiers , but basically, if an entity has an identifier, it's then a blue class, and AFAICT, it's the blue classes which have there terms defined in the generated context. You could test this in a copy or working version of the UNTP domain - if you add an id, is Dimension then in the generated context (which would make the error disappear). The problem is, Dimension shouldn't have a unique identifier - it's really a value, not a uniquely identifiable entity. I had a similar (but not the same) issue in the past and raised it as jargon-sh/issues#43 .

I'm not 100%, but I think this might be a mis-match between Jargon and jsonld: for Jargon, having a unique id property means the entity type should be defined in the context. For jsonld, any entity can have a type, regardless of whether it has a unique id. Might be worth asking Alastair (via an issue or similar).

[gemini-code-assist]

The After (0.6.0) example for issuingParty within reportingStandard is inconsistent with the schema. According to packages/untp-test-suite/src/schemas/digitalProductPassport/v0.6.0/schema.json, the Standard type (which reportingStandard is) has an issuingParty object that does not include an idScheme. This example should be updated to be consistent with the schema and other examples in this guide (like referenceStandard.issuingParty) by removing the idScheme object.

Suggested change

	"issuingParty": {
	"id": "https://www.globalbattery.org/",
	"name": "Global Battery Alliance",
	"registeredId": "123456789",
	"idScheme": {
	"type": [
	"IdentifierScheme"
	],
	"id": "https://id.gs1.org/01/",
	"name": "Global Trade Identification Number (GTIN)"
	}
	},
	"issuingParty": {
	"id": "https://www.globalbattery.org/",
	"name": "Global Battery Alliance",
	"registeredId": "123456789"
	},

[ashleythedeveloper]

idScheme is a valid property. From memory, I believe this has something to do with the fact that Jargon only includes primitives within the schema when using object references. @absoludity, did Alastair get around to fixing this?

[ashleythedeveloper]

@karinaliauw, please see the comments above.

[karinaliauw]

@ashleythedeveloper committed minor typo - I will put the remaining Gemini reviews on hold until we heard back from Alastair.

[karinaliauw]

Hi @ashleythedeveloper following up on this PR. Let me know you have any questions. Thank you.

[marcelab3]

Hi @ashleythedeveloper following up on Karina's updates. Thank you!