Adding & Maintaining Crates
Create a new crate
Section titled “Create a new crate”- Duplicate the
template/directory and rename it to your slug (lowercase letters, numbers, hyphens). - Update the copied
ro-crate-metadata.jsonwith your service-specific data. Keep only the fields you intend to populate. - Keep the files referenced in
hasPart(fdl.yml,script.sh,icon.png, optionalsample-input.txt) in sync with reality—either provide the files or remove the references. - Include any deployment notes (
README.md, sample payloads) that users might need to exercise the service.
Required metadata
Section titled “Required metadata”The ./ dataset node must include:
name: Human-friendly service name.description: Two or three sentences describing what the service does and how OSCAR users benefit.serviceType: A string or array of execution types, such assynchronous,asynchronous,exposed, ormodel-serving. The catalog derives filter options from the metadata automatically.license: Link or inline object describing the license.author: UseGRyCAP-UPVfor the repository owner in the crate metadata. Individual contribution history is maintained through Git commits and pull requests.url(or legacyURL): Target application endpoint, repository, or landing page.datePublished:YYYY-MM-DDformat.hasPart: Entries forfdl.ymlandscript.sh(both files are mandatory in every crate).
Include optional-but-valuable fields when available: memoryRequirements, processorRequirements, softwareRequirements, keywords, and version.
To keep the project metadata consistent, the crate author should be
GRyCAP-UPVas the repository owner. Individual contributors are still credited in Git history and commit metadata.
Testing metadata
Section titled “Testing metadata”Run the build locally to ensure the crate is parsed correctly:
npm run build && rocrate-validator validate -p ro-crate-1.1 --no-paging ./crates/<service>- The build will warn if an icon is missing or if the dataset node cannot be found.
rocrate-validator(Python) or any JSON-LD validator confirms structural correctness whenever you tweak schema-heavy sections.
Automatic catalog publication
Section titled “Automatic catalog publication”On every push to main, the Pages workflow runs the catalog tests and npm run build, then publishes dist/. The build discovers crates automatically and generates both the catalog entry and /services/<slug>/ detail page. New service types appear in the filter without editing the frontend. Descriptions are summarized in the catalog and displayed in full on the detail page, which also includes the original RO-Crate JSON.
Run npm test to verify catalog generation and filtering before opening a pull request.
Keeping crates up to date
Section titled “Keeping crates up to date”- Version updates: Increment
datePublished, and describe the change in the pull request. - Deprecations: Mention alternatives in the dataset
descriptionand note the status in the pull request if a service is being retired. - Icon refresh: Replace the PNG and ensure the aspect ratio stays square so catalog icons render uniformly.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Fix |
|---|---|
| Crate missing from the catalog | Check for JSON syntax errors or missing ./ dataset node. Run npm run dev and inspect the console warnings. |
| Icon placeholder shows initials | Confirm the dataset logo reference points to icon.png and that the file exists. |
| Filters misbehave | Ensure serviceType uses lowercase strings or an array of strings. Filter options are generated automatically from all crates. |
Once your crate passes these checks, open a pull request referencing the relevant issue.