kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/.opencode/rules/no-tool-specific-classes-rule.md
kempersc ee5e8e5a7c Refactor schema classes to enhance descriptions and mappings 
- Updated descriptions for EADDownload, EBook, EcclesiasticalProvince, EconomicArchive, EconomicArchiveRecordSetType, Edition, Editor, Education, EducationFacilityType, EducationLevel, and EducationProviderSubtype to improve clarity and multilingual support.
- Introduced alternative descriptions and structured aliases for better localization.
- Adjusted mappings to align with broader and close ontology relationships.
- Added new ConflictTypes schema with detailed classifications for various crisis categories affecting heritage.
2026-02-15 18:46:11 +01:00

1.3 KiB
Raw Blame History

Rule: No Tool-Specific Classes

Critical Convention

Ontology classes MUST be domain concepts, not wrappers for specific software tools.

Rule

  1. Do not model vendor/tool names as primary class concepts.

    • Reject classes like ExaSearchMetadata, OpenAIFetchResult, ElasticsearchHit.

  2. Model the generic domain activity or entity instead.

    • Use names like ExternalSearchMetadata, RetrievalActivity, SearchResult.

  3. Capture tool provenance through generic slots and values.

    • Use has_tool, has_method, has_agent, has_note to record implementation details.

  4. Platform custodians are allowed as domain classes.

    • Classes for digital platforms that act as custodians (for example YouTube-related custodian classes) are valid.
    • Operational tools used to query/process data are not valid ontology classes.

Rationale

  • Tool names are implementation details and change faster than domain semantics.
  • Tool-specific classes reduce reuse and interoperability.
  • Generic classes preserve stable meaning while still supporting full provenance.

Examples

Wrong

classes:
  ExaSearchMetadata:
    class_uri: prov:Activity

Correct

classes:
  ExternalSearchMetadata:
    class_uri: prov:Activity
    slots:
      - has_tool
      - has_method
      - has_agent