USGIN Metadata Building Blocks Repository

Created by S.M. Richard and claude-code 2026-02-15

Modular schema components following the OGC Building Blocks pattern for the IEDA Data Submission Portal and for implementation of modular inteoperable metadata for the Cross-Domain Interoperability Framework (CDIF). Each building block is a self-contained directory with a JSON Schema, JSON-LD context, metadata, and description. Building blocks compose into profiles that define complete metadata schemas for specific use cases.

For more info see the OGC Documentation.

Schema Pipeline

The schema pipeline transforms modular YAML source schemas into JSON Forms-compatible Draft 7 schemas in two steps, plus an augmentation step for the bblocks-viewer:

schema.yaml → resolve_schema.py → resolvedSchema.json → convert_for_jsonforms.py → schema.json
                                                       → augment_register.py → register.json (adds resolvedSchema URLs)

Step 1: Resolve (resolve_schema.py)

Recursively resolves all $ref references from modular YAML/JSON source schemas into one fully-inlined JSON Schema. Handles relative paths, fragment-only refs (#/$defs/X), cross-file fragments, and both YAML/JSON extensions. Optionally flattens allOf entries.

# Resolve a profile by name (searches adaProfiles/ and cdifProfiles/ subdirectories)
python tools/resolve_schema.py adaProduct

# Resolve all building blocks with external $refs
python tools/resolve_schema.py --all

# Resolve an arbitrary schema file
python tools/resolve_schema.py --file path/to/any/schema.yaml

Requirements: Python 3.6+ with pyyaml (pip install pyyaml)

Step 2: Convert for JSON Forms (convert_for_jsonforms.py)

Reads resolvedSchema.json and converts to JSON Forms-compatible Draft 7:

• Converts $schema from Draft 2020-12 to Draft 7
• Simplifies anyOf patterns for form rendering
• Converts contains → enum, const → default
• Merges technique profile constraints into distribution branches
• Preserves oneOf in distribution (3 branches: single file, archive, WebAPI)
• Merges file-type anyOf (from files/schema.yaml) into flat hasPart item properties
• Removes not constraints and relaxes minItems

# Convert all profiles
python tools/convert_for_jsonforms.py --all -v

# Convert a single profile
python tools/convert_for_jsonforms.py adaEMPA -v

Step 3: Augment register.json (augment_register.py)

Adds resolvedSchema URLs to build/register.json for each profile building block that has a resolvedSchema.json file. This enables the bblocks-viewer's "Resolved (JSON)" button to fetch and display the fully resolved schema (all $ref inlined, allOf flattened).

python tools/augment_register.py

The generate-jsonforms workflow runs this automatically after schema conversion.

Profiles (40 total)

Profiles are organized into subdirectories: _sources/profiles/adaProfiles/ (36 ADA profiles) and _sources/profiles/cdifProfiles/ (4 CDIF profiles).

Profile	Description
adaProduct	Base ADA product metadata — distribution has 3 oneOf branches (single file, archive, WebAPI)
adaEMPA	Electron Microprobe Analysis — constrains component types to EMPA-valid file types
adaXRD	X-ray Diffraction — constrains to XRD-valid component and file types
adaICPMS	ICP Mass Spectrometry — constrains to ICP-MS-valid component and file types (HR/Q/MC)
adaVNMIR	Very-Near Mid-IR / FTIR — constrains to VNMIR-valid component and file types
CDIFDiscovery	CDIF Discovery profile — general-purpose dataset metadata
31 more	Generated by tools/generate_profiles.py: adaAIVA, adaAMS, adaARGT, adaDSC, adaEAIRMS, adaFTICRMS, adaGCMS, adaGPYC, adaIC, adaICPOES, adaL2MS, adaLAF, adaLCMS, adaLIT, adaNGNSMS, adaNanoIR, adaNanoSIMS, adaPSFD, adaQRIS, adaRAMAN, adaRITOFNGMS, adaSEM, adaSIMS, adaSLS, adaSVRUEC, adaTEM, adaToFSIMS, adaUVFM, adaVLM, adaXANES, adaXCT

Run python tools/generate_profiles.py --list to see all generated profiles with their termcodes and detail building block info.

See agents.md for the full building block structure, authoring rules, and composition hierarchy.

License

This material is based upon work supported by the National Science Foundation (NSF) under awards 2012893, 2012748, and 2012593.