Schema: Croissant/schema.org Extension Design

[PipFoweraker]

Goal

Design a JSON-LD schema that extends Croissant / schema.org to represent interrogatory model cards, maximizing interoperability with existing tooling.

Why Croissant/schema.org?

1. JSON-LD foundation - machine-readable, web-native, supports linked data
2. Existing adoption - HuggingFace, Kaggle, Google Dataset Search use Croissant
3. Extensible - designed for domain-specific vocabularies
4. Future-proof - constrains future users least; can render to other formats

Design Questions

Namespace & Vocabulary

• Define @context extending schema.org and Croissant
• Identify which schema.org types to reuse (e.g., SoftwareSourceCode, Dataset, CreativeWork)
• Define new types: InterrogatoryModelCard, ModelClaim, EvidenceLink, InterrogatoryPrompt

CAN/SHOULD/MUST Representation

• How to represent requirement levels in JSON-LD?
• Consider RFC 2119 terminology mapping
• Schema validation: which fields required vs optional at each level?

Relationship to CycloneDX ML-BOM

• CycloneDX v1.5+ has modelCard field - should we output compatible fragments?
• Supply chain use case: can interrogatory cards feed into ML-BOM?

Evidence Linking Schema

• How to represent dataset_version, eval_script_commit, run_hash?
• Git-based provenance: reference commits, tags, releases?
• External artifact stores (HF, Weights & Biases, DVC)?

Deliverables

1. schema/interrogatory-model-card.jsonld - JSON-LD context definition
2. schema/interrogatory-model-card.schema.json - JSON Schema for validation
3. Example card in both formats demonstrating all field types

Resources

• Croissant Spec
• schema.org
• CycloneDX ML-BOM
• AI Cards paper - APF 2024 approach

Open Questions

1. Should the schema be strict (all MUST fields required) or permissive (flag missing fields)?
2. How to handle proprietary models with limited disclosure?
3. Versioning strategy for the schema itself?

[PipFoweraker]

Design Decision: Permissive Schema with Explicit Non-Disclosure

Per discussion, the schema should be permissive rather than strict:

• Fields are optional, not required
• Missing/refused disclosures are explicitly flagged rather than blocking
• Adoption highlights failure to disclose more than rejection would

Implementation

Each field should support:

{
  "training_data_sources": {
    "disclosed": false,
    "reason": "proprietary",
    "attestation": null
  }
}

vs

{
  "training_data_sources": {
    "disclosed": true,
    "value": ["Common Crawl", "Wikipedia", "..."],
    "evidence": { ... }
  }
}

Benefits

1. Lower adoption barrier - proprietary actors can use the schema
2. Transparency through structure - refusal to disclose becomes visible, comparable
3. Social pressure - "we use interrogatory model cards" becomes hollow if everything is disclosed: false
4. Gradient of disclosure - partial disclosure is better than no card at all

Completeness Score

Consider a "disclosure completeness" metric:

• Count of disclosed: true fields / total fields
• Weighted by MUST/SHOULD/CAN levels
• Displayed prominently on rendered cards

This makes non-disclosure legible without making adoption impossible.