Skip to content

Commit 2a6cbb1

Browse files
jdsikajdsika
authored
feat(EVES-003): add 1b Asset Preparation with input_manifest.json (#37)
* feat(EVES-003): add §1b Asset Preparation with input_manifest.json 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. * fix: align table header pipes in EVES-007 (MD060) --------- Signed-off-by: jdsika <carlo.van-driesten@bmw.de>
1 parent 337fda9 commit 2a6cbb1

3 files changed

Lines changed: 181 additions & 1 deletion

File tree

‎EVES/EVES-003/eves-003.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,103 @@ Asset examples can be found in the following repositories:
4545
- [Scenario Asset Example](https://github.com/ASCS-eV/scenario-asset-example)
4646
- [OSI-Trace Asset Example](https://github.com/ASCS-eV/ositrace-asset-example/tree/main)
4747

48+
### 1b. Asset Preparation
49+
50+
Before uploading, an asset MUST be organized into a well-defined folder structure and described by an input manifest.
51+
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`.
52+
53+
#### Folder Structure
54+
55+
Every `asset.zip` MUST contain the following top-level folders mapped to `envited-x` artifact categories:
56+
57+
| Folder | `envited-x` Category | Required | `envited-x` Access Role | Description |
58+
| --- | --- | --- | --- | --- |
59+
| `simulation-data/` | `envited-x:isSimulationData` | MUST | `envited-x:isOwner` | Core simulation data (e.g., `.xodr`, `.xosc`) |
60+
| `documentation/` | `envited-x:isDocumentation` | MUST | `envited-x:isPublic` | Documentation files (e.g., `.pdf`, `.txt`) |
61+
| `metadata/` | `envited-x:isMetadata` | MUST | `envited-x:isPublic` | Domain metadata (e.g., `hdmap_instance.json`) |
62+
| `media/` | `envited-x:isMedia` | MUST | `envited-x:isPublic` | Visualizations, images, GeoJSON, 3D previews |
63+
| `validation-reports/` | `envited-x:isValidationReport` | RECOMMENDED | `envited-x:isPublic` | Quality checker reports (e.g., `.xqar`, `.txt`) |
64+
| _(root)_ | `envited-x:isLicense` | MUST | `envited-x:isPublic` | LICENSE file at the asset root |
65+
| _(root)_ | `envited-x:isManifest` | MUST | `envited-x:isPublic` | `manifest_reference.json` at the asset root |
66+
67+
> **Note:** The `envited-x` categories and access roles are formally defined in the [ENVITED-X Ontology][21] which extends the generic [Manifest Ontology][22].
68+
> The `envited-x:ExtendedLinkShape` constrains the allowed values for both `manifest:hasCategory` and `manifest:hasAccessRole`.
69+
70+
#### Input Manifest (`input_manifest.json`)
71+
72+
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.
73+
It uses the same vocabulary as the final `manifest_reference.json` but omits computed fields (`cid`, `fileSize`, `timestamp`, `hasDimensions`, `filename`).
74+
75+
Each entry (a `manifest:Link`) MUST specify:
76+
77+
- `manifest:hasCategory` — one of the categories defined in the `envited-x` ontology
78+
- `manifest:hasAccessRole` — one of the access roles defined in the `envited-x` ontology
79+
- `manifest:hasFileMetadata` — a `manifest:FileMetadata` node with at minimum:
80+
- `manifest:filePath` (`xsd:anyURI`) — local file path or remote URL
81+
- `manifest:mimeType` (`xsd:string`) — MIME type of the file
82+
83+
##### Two-Stage Validation
84+
85+
Asset creation tooling SHOULD implement a two-stage validation approach:
86+
87+
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.
88+
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`).
89+
90+
##### Example `input_manifest.json`
91+
92+
See 📁 `example/input_manifest.json` for a complete example.
93+
94+
```json
95+
{
96+
"@context": [
97+
"https://w3id.org/ascs-ev/envited-x/manifest/v5/",
98+
{ "envited-x": "https://w3id.org/ascs-ev/envited-x/envited-x/v3/" }
99+
],
100+
"@id": "did:web:registry.gaia-x.eu:HdMap:example",
101+
"@type": "envited-x:Manifest",
102+
"hasArtifacts": [
103+
{
104+
"@type": "Link",
105+
"hasCategory": { "@id": "envited-x:isSimulationData" },
106+
"hasAccessRole": { "@id": "envited-x:isOwner" },
107+
"hasFileMetadata": {
108+
"@type": "FileMetadata",
109+
"filePath": "my_map.xodr",
110+
"mimeType": "application/xml"
111+
}
112+
},
113+
{
114+
"@type": "Link",
115+
"hasCategory": { "@id": "envited-x:isMedia" },
116+
"hasAccessRole": { "@id": "envited-x:isPublic" },
117+
"hasFileMetadata": {
118+
"@type": "FileMetadata",
119+
"filePath": "impression-01.png",
120+
"mimeType": "image/png"
121+
}
122+
}
123+
],
124+
"hasLicense": {
125+
"@type": "Link",
126+
"hasCategory": { "@id": "envited-x:isLicense" },
127+
"hasAccessRole": { "@id": "envited-x:isPublic" },
128+
"hasFileMetadata": {
129+
"@type": "FileMetadata",
130+
"filePath": "LICENSE",
131+
"mimeType": "text/plain"
132+
}
133+
}
134+
}
135+
```
136+
137+
The asset creation pipeline enriches this into a full `manifest_reference.json` by:
138+
139+
1. Computing `manifest:cid` (IPFS CIDv1) for each file
140+
2. Computing `manifest:fileSize` and `manifest:timestamp`
141+
3. Extracting `manifest:hasDimensions` for images
142+
4. Adding generated artifacts (documentation, metadata, validation reports)
143+
5. Adding the self-referencing `manifest:hasManifestReference` entry
144+
48145
### 2. Pinata IPFS and CID Management
49146

50147
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
75172

76173
#### Step 1: Client-Side Pre-Validation
77174

175+
- Verify that an `input_manifest.json` was used during asset preparation (see [§1b](#1b-asset-preparation)):
176+
1. Each `manifest:Link` in the input SHOULD have been validated against `manifest:LinkShape` and `envited-x:ExtendedLinkShape`.
78177
- Drag and drop `asset.zip` into the upload field.
79178
- Validate the `manifest_reference.json`:
80179
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
212311
- [RFC 2119: Key Words for Use in RFCs to Indicate Requirement Levels][16]
213312
- [Gaia-X Policy Rules Compliance Document (Release 24.11)][17]
214313
- [Marketplace Contract Reference Implementation][18]
314+
- [ENVITED-X Simulation Asset Tools][20]
315+
- [ENVITED-X Ontology][21]
316+
- [Manifest Ontology][22]
317+
- [ENVITED-X Simulation Asset Tools][20]
318+
- [ENVITED-X Ontology][21]
319+
- [Manifest Ontology][22]
215320

216321
[1]: https://github.com/ASCS-eV/ontology-management-base/
217322
[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
232337
[17]: https://docs.gaia-x.eu/policy-rules-committee/compliance-document/24.11/
233338
[18]: https://github.com/ASCS-eV/smart-contracts/tree/main/contracts/marketplace/
234339
[19]: https://github.com/GAIA-X4PLC-AAD/ontology-management-base/tree/main/tzip21
340+
[20]: https://github.com/openMSL/sl-5-8-asset-tools
341+
[21]: https://github.com/ASCS-eV/ontology-management-base/tree/main/artifacts/envited-x
342+
[22]: https://github.com/ASCS-eV/ontology-management-base/tree/main/artifacts/manifest

‎EVES/EVES-003/example/input_manifest.json‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
{
2+
"@context": [
3+
"https://w3id.org/ascs-ev/envited-x/manifest/v5/",
4+
{
5+
"envited-x": "https://w3id.org/ascs-ev/envited-x/envited-x/v3/"
6+
}
7+
],
8+
"@id": "did:web:registry.gaia-x.eu:HdMap:Testfeld_Niedersachsen_ALKS_xodr_sample_offset",
9+
"@type": "envited-x:Manifest",
10+
"hasArtifacts": [
11+
{
12+
"@type": "Link",
13+
"hasCategory": { "@id": "envited-x:isSimulationData" },
14+
"hasAccessRole": { "@id": "envited-x:isOwner" },
15+
"hasFileMetadata": {
16+
"@type": "FileMetadata",
17+
"filePath": "Testfeld_Niedersachsen_ALKS_xodr_sample_offset.xodr",
18+
"mimeType": "application/xml"
19+
}
20+
},
21+
{
22+
"@type": "Link",
23+
"hasCategory": { "@id": "envited-x:isMedia" },
24+
"hasAccessRole": { "@id": "envited-x:isPublic" },
25+
"hasFileMetadata": {
26+
"@type": "FileMetadata",
27+
"filePath": "impression-01.png",
28+
"mimeType": "image/png"
29+
}
30+
},
31+
{
32+
"@type": "Link",
33+
"hasCategory": { "@id": "envited-x:isMedia" },
34+
"hasAccessRole": { "@id": "envited-x:isPublic" },
35+
"hasFileMetadata": {
36+
"@type": "FileMetadata",
37+
"filePath": "impression-02.png",
38+
"mimeType": "image/png"
39+
}
40+
},
41+
{
42+
"@type": "Link",
43+
"hasCategory": { "@id": "envited-x:isMedia" },
44+
"hasAccessRole": { "@id": "envited-x:isPublic" },
45+
"hasFileMetadata": {
46+
"@type": "FileMetadata",
47+
"filePath": "impression-03.png",
48+
"mimeType": "image/png"
49+
}
50+
},
51+
{
52+
"@type": "Link",
53+
"hasCategory": { "@id": "envited-x:isDocumentation" },
54+
"hasAccessRole": { "@id": "envited-x:isPublic" },
55+
"hasFileMetadata": {
56+
"@type": "FileMetadata",
57+
"filePath": "documentation.txt",
58+
"mimeType": "text/plain"
59+
}
60+
}
61+
],
62+
"hasLicense": {
63+
"@type": "Link",
64+
"hasCategory": { "@id": "envited-x:isLicense" },
65+
"hasAccessRole": { "@id": "envited-x:isPublic" },
66+
"hasFileMetadata": {
67+
"@type": "FileMetadata",
68+
"filePath": "https://www.mozilla.org/en-US/MPL/2.0/",
69+
"mimeType": "text/html"
70+
}
71+
}
72+
}

‎EVES/EVES-007/eves-007.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ urn:blockchain:{chain_namespace}:{chain_id}:contract:{contract_address}
4545

4646
##### Smart Contract Example Mappings
4747

48-
| Blockchain | Namespace | Chain ID | Example URN |
48+
| Blockchain | Namespace | Chain ID | Example URN |
4949
|-------------------------|-----------|-------------------|--------------------------------------------------------------------------------------|
5050
| **Tezos (Ghostnet)** | `tezos` | `NetXnHfVqm9iesp` | `urn:blockchain:tezos:NetXnHfVqm9iesp:contract:KT1PCaD2kmgCHy15wQ1gpqZUy9RLxyBVJdTF` |
5151
| **Ethereum (Mainnet)** | `eip155` | `1` | `urn:blockchain:eip155:1:contract:0xABC123456789...` |

0 commit comments

Comments
 (0)