Skip to content

Adding & Maintaining Crates

  1. Duplicate the template/ directory and rename it to your slug (lowercase letters, numbers, hyphens).
  2. Update the copied ro-crate-metadata.json with your service-specific data. Keep only the fields you intend to populate.
  3. Keep the files referenced in hasPart (fdl.yml, script.sh, icon.png, optional sample-input.txt) in sync with reality—either provide the files or remove the references.
  4. Include any deployment notes (README.md, sample payloads) that users might need to exercise the service.

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 as synchronous, asynchronous, exposed, or model-serving. The catalog derives filter options from the metadata automatically.
  • license: Link or inline object describing the license.
  • author: Use GRyCAP-UPV for the repository owner in the crate metadata. Individual contribution history is maintained through Git commits and pull requests.
  • url (or legacy URL): Target application endpoint, repository, or landing page.
  • datePublished: YYYY-MM-DD format.
  • hasPart: Entries for fdl.yml and script.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-UPV as the repository owner. Individual contributors are still credited in Git history and commit metadata.

Run the build locally to ensure the crate is parsed correctly:

Terminal window
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.

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.

  • Version updates: Increment datePublished, and describe the change in the pull request.
  • Deprecations: Mention alternatives in the dataset description and 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.
SymptomFix
Crate missing from the catalogCheck for JSON syntax errors or missing ./ dataset node. Run npm run dev and inspect the console warnings.
Icon placeholder shows initialsConfirm the dataset logo reference points to icon.png and that the file exists.
Filters misbehaveEnsure 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.