updated publisher spec

[0x73746F66]

TLDR

The TEA Publisher OpenAPI specification has inconsistencies with the consumer API
and documentation, causing potential integration issues and confusion for implementers in the upcoming Beta 1 hackathon on May 28th.

---

• Extended parameter documentation to be more complete
• We now have schema examples
• Version number updated to 0.0.3 to match consumer API

This PR is focussed on the Publisher API spec, that was mostly unchanged since my last contrinution. I noticed it needed significant updates to align with the latest architecture documentation and all the updated that had been given to the consumer API spec (how would consumers consume things that weren't able to be published? This had to be fixed!)

Incompatibilities with consumer spec

1. Field Naming Inconsistencies:

Consumer: Uses url in artifact format
Publisher: Uses artifact_url in artifact format

2. Parameter Structure:

Consumer: Uses id-type/id-value for product queries
Publisher: Uses direct filter parameters

3. Missing Consumer Endpoints:

• /release/{uuid}/collection for latest collection
• /release/{uuid}/collections for all collections
• /artifact/{uuid} for artifact metadata

4. Schema Differences:

Consumer requires versions field in component schema
Publisher's component doesn't match this requirement

Changes

1. Terminology Standardization

Before:

• Used leaf endpoints and schemas in publisher API
• Inconsistent with consumer API's component/release model

After:

• Replaced with proper /component and /release endpoints
• Aligned object model with documentation

Why: Consistent terminology across consumer/publisher APIs prevents integration errors.

2. TEI URN Integration

Before:

• Limited TEI support in product endpoints
• No validation for TEI URN format

After:

• Added tei_urns array to product schema
• Implemented URI pattern validation: ^urn:tei:[a-zA-Z0-9]+:[a-zA-Z0-9\\.-]+:.+$

Why: TEI URNs are the primary discovery mechanism according to documentation.

3. Collection Update Mechanism

Before:

• Collection update reasons used undocumented enum values
• No clear versioning mechanism

After:

• Added proper collection_update_reason schema with values from docs:
  • INITIAL_RELEASE
  • VEX_UPDATED
  • ARTIFACT_UPDATED
  • ARTIFACT_ADDED
  • ARTIFACT_REMOVED
• Added /collection/{uuid}/{version} endpoint

Why: Matches documented collection versioning requirements.

4. Artifact Structure

Before:

• Used inconsistent artifact structure with objects
• Single checksum value per artifact

After:

• Aligned with consumer API using formats array
• Multiple checksums with algorithm type support
• Consistent properties with consumer API

Why: Allows full interoperability between consumer/publisher systems.

5. Component/Release Relationship

Before:

• Flat hierarchy with limited relationships between objects

After:

• Clear product → component → release → collection hierarchy
• Proper reference arrays between object types

Why: Matches documented model and enables proper artifact organization.