From cbb4192a60e3499d113a4ead86287ef2a20f2dab Mon Sep 17 00:00:00 2001 From: jdsika Date: Tue, 10 Mar 2026 13:52:10 +0100 Subject: [PATCH 1/2] =?UTF-8?q?feat(EVES-003):=20add=20=C2=A71b=20Asset=20?= =?UTF-8?q?Preparation=20with=20input=5Fmanifest.json?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add new section §1b that formalizes the asset preparation process: - Normative folder-to-category mapping table linking directory structure to envited-x ontology categories and access roles - input_manifest.json specification as a partial envited-x:Manifest in JSON-LD that describes user-provided input files - Two-stage validation model: per-Link input validation (fail fast) followed by full ManifestShape output validation (completeness) - Example input_manifest.json in the example/ folder - Updated Step 1 to reference input manifest pre-validation - Added references to ENVITED-X Simulation Asset Tools, ENVITED-X Ontology, and Manifest Ontology The input_manifest.json replaces the ad-hoc uploadedFiles.json format by using the same envited-x vocabulary throughout the pipeline (input -> processing -> output), enabling SHACL validation at every stage. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: jdsika --- EVES/EVES-003/eves-003.md | 108 ++++++++++++++++++++++ EVES/EVES-003/example/input_manifest.json | 72 +++++++++++++++ 2 files changed, 180 insertions(+) create mode 100644 EVES/EVES-003/example/input_manifest.json diff --git a/EVES/EVES-003/eves-003.md b/EVES/EVES-003/eves-003.md index 282c3cc..b296606 100644 --- a/EVES/EVES-003/eves-003.md +++ b/EVES/EVES-003/eves-003.md @@ -45,6 +45,103 @@ Asset examples can be found in the following repositories: - [Scenario Asset Example](https://github.com/ASCS-eV/scenario-asset-example) - [OSI-Trace Asset Example](https://github.com/ASCS-eV/ositrace-asset-example/tree/main) +### 1b. Asset Preparation + +Before uploading, an asset MUST be organized into a well-defined folder structure and described by an input manifest. +Tooling such as the [ENVITED-X Simulation Asset Tools][20] MAY automate the creation of a conformant `asset.zip` from user-provided input files and an `input_manifest.json`. + +#### Folder Structure + +Every `asset.zip` MUST contain the following top-level folders mapped to `envited-x` artifact categories: + +| Folder | `envited-x` Category | Required | `envited-x` Access Role | Description | +| --- | --- | --- | --- | --- | +| `simulation-data/` | `envited-x:isSimulationData` | MUST | `envited-x:isOwner` | Core simulation data (e.g., `.xodr`, `.xosc`) | +| `documentation/` | `envited-x:isDocumentation` | MUST | `envited-x:isPublic` | Documentation files (e.g., `.pdf`, `.txt`) | +| `metadata/` | `envited-x:isMetadata` | MUST | `envited-x:isPublic` | Domain metadata (e.g., `hdmap_instance.json`) | +| `media/` | `envited-x:isMedia` | MUST | `envited-x:isPublic` | Visualizations, images, GeoJSON, 3D previews | +| `validation-reports/` | `envited-x:isValidationReport` | RECOMMENDED | `envited-x:isPublic` | Quality checker reports (e.g., `.xqar`, `.txt`) | +| _(root)_ | `envited-x:isLicense` | MUST | `envited-x:isPublic` | LICENSE file at the asset root | +| _(root)_ | `envited-x:isManifest` | MUST | `envited-x:isPublic` | `manifest_reference.json` at the asset root | + +> **Note:** The `envited-x` categories and access roles are formally defined in the [ENVITED-X Ontology][21] which extends the generic [Manifest Ontology][22]. +> The `envited-x:ExtendedLinkShape` constrains the allowed values for both `manifest:hasCategory` and `manifest:hasAccessRole`. + +#### Input Manifest (`input_manifest.json`) + +An `input_manifest.json` is a partial `envited-x:Manifest` in JSON-LD that describes the user-provided input files before the asset creation pipeline processes them. +It uses the same vocabulary as the final `manifest_reference.json` but omits computed fields (`cid`, `fileSize`, `timestamp`, `hasDimensions`, `filename`). + +Each entry (a `manifest:Link`) MUST specify: + +- `manifest:hasCategory` — one of the categories defined in the `envited-x` ontology +- `manifest:hasAccessRole` — one of the access roles defined in the `envited-x` ontology +- `manifest:hasFileMetadata` — a `manifest:FileMetadata` node with at minimum: + - `manifest:filePath` (`xsd:anyURI`) — local file path or remote URL + - `manifest:mimeType` (`xsd:string`) — MIME type of the file + +##### Two-Stage Validation + +Asset creation tooling SHOULD implement a two-stage validation approach: + +1. **Input validation (fail fast):** Each `manifest:Link` in the `input_manifest.json` SHOULD be validated against `manifest:LinkShape` and `envited-x:ExtendedLinkShape` before the pipeline runs. This catches invalid categories, missing access roles, or malformed file metadata early. +2. **Output validation (completeness):** The completed `manifest_reference.json` MUST be validated against the full `envited-x:ManifestShape`, which requires at least one artifact per core category (`isSimulationData`, `isDocumentation`, `isMetadata`, `isMedia`). + +##### Example `input_manifest.json` + +See 📁 `example/input_manifest.json` for a complete example. + +```json +{ + "@context": [ + "https://w3id.org/ascs-ev/envited-x/manifest/v5/", + { "envited-x": "https://w3id.org/ascs-ev/envited-x/envited-x/v3/" } + ], + "@id": "did:web:registry.gaia-x.eu:HdMap:example", + "@type": "envited-x:Manifest", + "hasArtifacts": [ + { + "@type": "Link", + "hasCategory": { "@id": "envited-x:isSimulationData" }, + "hasAccessRole": { "@id": "envited-x:isOwner" }, + "hasFileMetadata": { + "@type": "FileMetadata", + "filePath": "my_map.xodr", + "mimeType": "application/xml" + } + }, + { + "@type": "Link", + "hasCategory": { "@id": "envited-x:isMedia" }, + "hasAccessRole": { "@id": "envited-x:isPublic" }, + "hasFileMetadata": { + "@type": "FileMetadata", + "filePath": "impression-01.png", + "mimeType": "image/png" + } + } + ], + "hasLicense": { + "@type": "Link", + "hasCategory": { "@id": "envited-x:isLicense" }, + "hasAccessRole": { "@id": "envited-x:isPublic" }, + "hasFileMetadata": { + "@type": "FileMetadata", + "filePath": "LICENSE", + "mimeType": "text/plain" + } + } +} +``` + +The asset creation pipeline enriches this into a full `manifest_reference.json` by: + +1. Computing `manifest:cid` (IPFS CIDv1) for each file +2. Computing `manifest:fileSize` and `manifest:timestamp` +3. Extracting `manifest:hasDimensions` for images +4. Adding generated artifacts (documentation, metadata, validation reports) +5. Adding the self-referencing `manifest:hasManifestReference` entry + ### 2. Pinata IPFS and CID Management It is RECOMMENDED to use [IPFS][8] within the ENVITED-X Data Space for making public data available. @@ -75,6 +172,8 @@ The following process is implemented in the [ENVITED-X Data Space][12] portal de #### Step 1: Client-Side Pre-Validation +- Verify that an `input_manifest.json` was used during asset preparation (see [§1b](#1b-asset-preparation)): + 1. Each `manifest:Link` in the input SHOULD have been validated against `manifest:LinkShape` and `envited-x:ExtendedLinkShape`. - Drag and drop `asset.zip` into the upload field. - Validate the `manifest_reference.json`: 1. Ensure JSON structure matches the manifest SHACL constraints. @@ -212,6 +311,12 @@ The compatibility with the current release of the [Gaia-X Policy Rules Complianc - [RFC 2119: Key Words for Use in RFCs to Indicate Requirement Levels][16] - [Gaia-X Policy Rules Compliance Document (Release 24.11)][17] - [Marketplace Contract Reference Implementation][18] +- [ENVITED-X Simulation Asset Tools][20] +- [ENVITED-X Ontology][21] +- [Manifest Ontology][22] +- [ENVITED-X Simulation Asset Tools][20] +- [ENVITED-X Ontology][21] +- [Manifest Ontology][22] [1]: https://github.com/ASCS-eV/ontology-management-base/ [2]: https://github.com/GAIA-X4PLC-AAD/ontology-management-base/tree/main/gx @@ -232,3 +337,6 @@ The compatibility with the current release of the [Gaia-X Policy Rules Complianc [17]: https://docs.gaia-x.eu/policy-rules-committee/compliance-document/24.11/ [18]: https://github.com/ASCS-eV/smart-contracts/tree/main/contracts/marketplace/ [19]: https://github.com/GAIA-X4PLC-AAD/ontology-management-base/tree/main/tzip21 +[20]: https://github.com/openMSL/sl-5-8-asset-tools +[21]: https://github.com/ASCS-eV/ontology-management-base/tree/main/artifacts/envited-x +[22]: https://github.com/ASCS-eV/ontology-management-base/tree/main/artifacts/manifest diff --git a/EVES/EVES-003/example/input_manifest.json b/EVES/EVES-003/example/input_manifest.json new file mode 100644 index 0000000..fc1265a --- /dev/null +++ b/EVES/EVES-003/example/input_manifest.json @@ -0,0 +1,72 @@ +{ + "@context": [ + "https://w3id.org/ascs-ev/envited-x/manifest/v5/", + { + "envited-x": "https://w3id.org/ascs-ev/envited-x/envited-x/v3/" + } + ], + "@id": "did:web:registry.gaia-x.eu:HdMap:Testfeld_Niedersachsen_ALKS_xodr_sample_offset", + "@type": "envited-x:Manifest", + "hasArtifacts": [ + { + "@type": "Link", + "hasCategory": { "@id": "envited-x:isSimulationData" }, + "hasAccessRole": { "@id": "envited-x:isOwner" }, + "hasFileMetadata": { + "@type": "FileMetadata", + "filePath": "Testfeld_Niedersachsen_ALKS_xodr_sample_offset.xodr", + "mimeType": "application/xml" + } + }, + { + "@type": "Link", + "hasCategory": { "@id": "envited-x:isMedia" }, + "hasAccessRole": { "@id": "envited-x:isPublic" }, + "hasFileMetadata": { + "@type": "FileMetadata", + "filePath": "impression-01.png", + "mimeType": "image/png" + } + }, + { + "@type": "Link", + "hasCategory": { "@id": "envited-x:isMedia" }, + "hasAccessRole": { "@id": "envited-x:isPublic" }, + "hasFileMetadata": { + "@type": "FileMetadata", + "filePath": "impression-02.png", + "mimeType": "image/png" + } + }, + { + "@type": "Link", + "hasCategory": { "@id": "envited-x:isMedia" }, + "hasAccessRole": { "@id": "envited-x:isPublic" }, + "hasFileMetadata": { + "@type": "FileMetadata", + "filePath": "impression-03.png", + "mimeType": "image/png" + } + }, + { + "@type": "Link", + "hasCategory": { "@id": "envited-x:isDocumentation" }, + "hasAccessRole": { "@id": "envited-x:isPublic" }, + "hasFileMetadata": { + "@type": "FileMetadata", + "filePath": "documentation.txt", + "mimeType": "text/plain" + } + } + ], + "hasLicense": { + "@type": "Link", + "hasCategory": { "@id": "envited-x:isLicense" }, + "hasAccessRole": { "@id": "envited-x:isPublic" }, + "hasFileMetadata": { + "@type": "FileMetadata", + "filePath": "https://www.mozilla.org/en-US/MPL/2.0/", + "mimeType": "text/html" + } + } +} From 6db1391ed8ea6c0c9eace23cb0205f5a6153f843 Mon Sep 17 00:00:00 2001 From: jdsika Date: Tue, 10 Mar 2026 22:28:24 +0100 Subject: [PATCH 2/2] fix: align table header pipes in EVES-007 (MD060) Signed-off-by: jdsika --- EVES/EVES-007/eves-007.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EVES/EVES-007/eves-007.md b/EVES/EVES-007/eves-007.md index b26c3dd..f146e5a 100644 --- a/EVES/EVES-007/eves-007.md +++ b/EVES/EVES-007/eves-007.md @@ -45,7 +45,7 @@ urn:blockchain:{chain_namespace}:{chain_id}:contract:{contract_address} ##### Smart Contract Example Mappings -| Blockchain | Namespace | Chain ID | Example URN | +| Blockchain | Namespace | Chain ID | Example URN | |-------------------------|-----------|-------------------|--------------------------------------------------------------------------------------| | **Tezos (Ghostnet)** | `tezos` | `NetXnHfVqm9iesp` | `urn:blockchain:tezos:NetXnHfVqm9iesp:contract:KT1PCaD2kmgCHy15wQ1gpqZUy9RLxyBVJdTF` | | **Ethereum (Mainnet)** | `eip155` | `1` | `urn:blockchain:eip155:1:contract:0xABC123456789...` |