Reference Models

This documentation auto-generates details about the Pydantic models defined in app/domain/references/models/models.py.

Models associated with references.

pydantic model app.domain.references.models.models.AnnotationFilter

Model representing an annotation filter for searching references.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "AnnotationFilter",
   "description": "Model representing an annotation filter for searching references.",
   "type": "object",
   "properties": {
      "scheme": {
         "description": "The annotation scheme to filter on.",
         "title": "Scheme",
         "type": "string"
      },
      "label": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The annotation label to filter on.",
         "title": "Label"
      },
      "score": {
         "anyOf": [
            {
               "maximum": 1.0,
               "minimum": 0.0,
               "type": "number"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Optional score threshold for the annotation filter.",
         "title": "Score"
      }
   },
   "required": [
      "scheme"
   ]
}

Fields:

• label (str | None)

• scheme (str)

• score (float | None)

field label: str | None = None

The annotation label to filter on.

field scheme: str [Required]

The annotation scheme to filter on.

field score: float | None = None

Optional score threshold for the annotation filter.

Constraints:

• ge = 0.0

• le = 1.0

pydantic model app.domain.references.models.models.Candidate

A candidate canonical reference with route provenance.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "Candidate",
   "description": "A candidate canonical reference with route provenance.",
   "type": "object",
   "properties": {
      "reference_id": {
         "format": "uuid",
         "title": "Reference Id",
         "type": "string"
      },
      "rank": {
         "description": "Overall rank across all routes (1-based).",
         "title": "Rank",
         "type": "integer"
      },
      "routes": {
         "description": "How this candidate was surfaced (ES and/or identifier).",
         "items": {
            "discriminator": {
               "mapping": {
                  "elasticsearch": "#/$defs/CandidateElasticsearchRoute",
                  "identifier": "#/$defs/CandidateIdentifierRoute"
               },
               "propertyName": "type"
            },
            "oneOf": [
               {
                  "$ref": "#/$defs/CandidateElasticsearchRoute"
               },
               {
                  "$ref": "#/$defs/CandidateIdentifierRoute"
               }
            ]
         },
         "title": "Routes",
         "type": "array"
      },
      "reference": {
         "anyOf": [
            {
               "$ref": "#/$defs/CandidateReference"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Hydrated bibliographic fields; omitted when hydrate is false."
      }
   },
   "$defs": {
      "CandidateElasticsearchRoute": {
         "description": "Provenance for a candidate surfaced by the Elasticsearch query.",
         "properties": {
            "type": {
               "const": "elasticsearch",
               "default": "elasticsearch",
               "title": "Type",
               "type": "string"
            },
            "policy": {
               "description": "The retrieval policy that surfaced the candidate.",
               "title": "Policy",
               "type": "string"
            },
            "rank": {
               "description": "Rank within the Elasticsearch results (1-based).",
               "title": "Rank",
               "type": "integer"
            },
            "score": {
               "description": "The Elasticsearch relevance score.",
               "title": "Score",
               "type": "number"
            }
         },
         "required": [
            "policy",
            "rank",
            "score"
         ],
         "title": "CandidateElasticsearchRoute",
         "type": "object"
      },
      "CandidateIdentifier": {
         "description": "An external identifier used as candidate-search input and match provenance.\n\nNarrows :class:`GenericExternalIdentifier` to require an explicit type;\ncandidate search does not accept database-id (untyped) lookups.",
         "properties": {
            "identifier": {
               "description": "The identifier itself.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "$ref": "#/$defs/ExternalIdentifierType",
               "description": "The type of the identifier, e.g. doi, pm_id, open_alex."
            },
            "other_identifier_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the other identifier.",
               "title": "Other Identifier Name"
            }
         },
         "required": [
            "identifier",
            "identifier_type"
         ],
         "title": "CandidateIdentifier",
         "type": "object"
      },
      "CandidateIdentifierRoute": {
         "description": "Provenance for a candidate surfaced by an exact identifier match.",
         "properties": {
            "type": {
               "const": "identifier",
               "default": "identifier",
               "title": "Type",
               "type": "string"
            },
            "matched_identifiers": {
               "description": "The input identifiers that matched this candidate.",
               "items": {
                  "$ref": "#/$defs/CandidateIdentifier"
               },
               "title": "Matched Identifiers",
               "type": "array"
            }
         },
         "required": [
            "matched_identifiers"
         ],
         "title": "CandidateIdentifierRoute",
         "type": "object"
      },
      "CandidateReference": {
         "description": "Hydrated bibliographic fields of a candidate reference.",
         "properties": {
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Title"
            },
            "authors": {
               "items": {
                  "type": "string"
               },
               "title": "Authors",
               "type": "array"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Publication Year"
            },
            "identifiers": {
               "items": {
                  "$ref": "#/$defs/CandidateIdentifier"
               },
               "title": "Identifiers",
               "type": "array"
            }
         },
         "title": "CandidateReference",
         "type": "object"
      },
      "ExternalIdentifierType": {
         "description": "The type of identifier used to identify a reference.\n\nThis is used to identify the type of identifier used in the `ExternalIdentifier`\nclass.",
         "enum": [
            "doi",
            "eric",
            "pm_id",
            "pro_quest",
            "open_alex",
            "other"
         ],
         "title": "ExternalIdentifierType",
         "type": "string"
      }
   },
   "required": [
      "reference_id",
      "rank",
      "routes"
   ]
}

Fields:

• rank (int)

• reference (app.domain.references.models.models.CandidateReference | None)

• reference_id (uuid.UUID)

• routes (list[app.domain.references.models.models.CandidateElasticsearchRoute | app.domain.references.models.models.CandidateIdentifierRoute])

field rank: int [Required]

Overall rank across all routes (1-based).

field reference: CandidateReference | None = None

Hydrated bibliographic fields; omitted when hydrate is false.

field reference_id: UUID [Required]

field routes: list[Annotated[CandidateElasticsearchRoute | CandidateIdentifierRoute, FieldInfo(annotation=NoneType, required=True, discriminator='type')]] [Required]

How this candidate was surfaced (ES and/or identifier).

pydantic model app.domain.references.models.models.CandidateCanonicalSearchFields

Fields used for candidate canonical selection.

The retrieval policy is interpreted by app.domain.references.services.deduplication_service.build_candidate_canonical_search_query().

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CandidateCanonicalSearchFields",
   "description": "Fields used for candidate canonical selection.\n\nThe retrieval policy is interpreted by\n:func:`app.domain.references.services.deduplication_service.build_candidate_canonical_search_query`.",
   "type": "object",
   "properties": {
      "publication_year": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The publication year of the reference.",
         "title": "Publication Year"
      },
      "authors": {
         "description": "The authors of the reference.",
         "items": {
            "type": "string"
         },
         "title": "Authors",
         "type": "array"
      },
      "title": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The title of the reference.",
         "title": "Title"
      }
   }
}

Fields:

• authors (list[str])

• publication_year (int | None)

• title (str | None)

field authors: list[str] [Optional]

The authors of the reference.

field publication_year: int | None = None

The publication year of the reference.

field title: str | None = None

The title of the reference.

property is_searchable: bool

Whether the projection has the fields required to search for candidates.

pydantic model app.domain.references.models.models.CandidateCanonicalSearchQuery

Service-owned candidate query specification for Elasticsearch translation.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CandidateCanonicalSearchQuery",
   "description": "Service-owned candidate query specification for Elasticsearch translation.",
   "type": "object",
   "properties": {
      "title": {
         "title": "Title",
         "type": "string"
      },
      "title_fuzziness": {
         "title": "Title Fuzziness",
         "type": "string"
      },
      "title_boost": {
         "title": "Title Boost",
         "type": "number"
      },
      "title_operator": {
         "const": "or",
         "title": "Title Operator",
         "type": "string"
      },
      "title_minimum_should_match": {
         "title": "Title Minimum Should Match",
         "type": "string"
      },
      "author_terms": {
         "items": {
            "type": "string"
         },
         "title": "Author Terms",
         "type": "array"
      },
      "author_tie_breaker": {
         "title": "Author Tie Breaker",
         "type": "number"
      },
      "publication_year_range": {
         "anyOf": [
            {
               "maxItems": 2,
               "minItems": 2,
               "prefixItems": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "integer"
                  }
               ],
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "title": "Publication Year Range"
      },
      "publication_year_decay": {
         "anyOf": [
            {
               "$ref": "#/$defs/YearDecay"
            },
            {
               "type": "null"
            }
         ],
         "default": null
      },
      "duplicate_determination": {
         "$ref": "#/$defs/DuplicateDetermination"
      },
      "excluded_reference_id": {
         "anyOf": [
            {
               "format": "uuid",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "title": "Excluded Reference Id"
      }
   },
   "$defs": {
      "DuplicateDetermination": {
         "description": "The determination of whether a reference is a duplicate.\n\nThis encodes both a status and a determination.",
         "enum": [
            "pending",
            "nominated",
            "duplicate",
            "exact_duplicate",
            "canonical",
            "unresolved",
            "unsearchable",
            "decoupled"
         ],
         "title": "DuplicateDetermination",
         "type": "string"
      },
      "YearDecay": {
         "description": "Resolved decay spec carried on a candidate query; origin is required.",
         "properties": {
            "offset": {
               "default": 1,
               "minimum": 0,
               "title": "Offset",
               "type": "integer"
            },
            "scale": {
               "default": 9,
               "exclusiveMinimum": 0,
               "title": "Scale",
               "type": "integer"
            },
            "decay": {
               "default": 0.5,
               "exclusiveMaximum": 1,
               "exclusiveMinimum": 0,
               "title": "Decay",
               "type": "number"
            },
            "weight": {
               "default": 0.1,
               "minimum": 0,
               "title": "Weight",
               "type": "number"
            },
            "origin": {
               "title": "Origin",
               "type": "integer"
            }
         },
         "required": [
            "origin"
         ],
         "title": "YearDecay",
         "type": "object"
      }
   },
   "required": [
      "title",
      "title_fuzziness",
      "title_boost",
      "title_operator",
      "title_minimum_should_match",
      "author_terms",
      "author_tie_breaker",
      "publication_year_range",
      "duplicate_determination",
      "excluded_reference_id"
   ]
}

Config:

• frozen: bool = True

Fields:

• author_terms (tuple[str, ...])

• author_tie_breaker (float)

• duplicate_determination (app.domain.references.models.models.DuplicateDetermination)

• excluded_reference_id (uuid.UUID | None)

• publication_year_decay (app.domain.references.models.models.YearDecay | None)

• publication_year_range (tuple[int, int] | None)

• title (str)

• title_boost (float)

• title_fuzziness (str)

• title_minimum_should_match (str)

• title_operator (Literal['or'])

field author_terms: tuple[str, ...] [Required]

field author_tie_breaker: float [Required]

field duplicate_determination: DuplicateDetermination [Required]

field excluded_reference_id: UUID | None [Required]

field publication_year_decay: YearDecay | None = None

field publication_year_range: tuple[int, int] | None [Required]

field title: str [Required]

field title_boost: float [Required]

field title_fuzziness: str [Required]

field title_minimum_should_match: str [Required]

field title_operator: Literal['or'] [Required]

pydantic model app.domain.references.models.models.CandidateElasticsearchRoute

Provenance for a candidate surfaced by the Elasticsearch query.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CandidateElasticsearchRoute",
   "description": "Provenance for a candidate surfaced by the Elasticsearch query.",
   "type": "object",
   "properties": {
      "type": {
         "const": "elasticsearch",
         "default": "elasticsearch",
         "title": "Type",
         "type": "string"
      },
      "policy": {
         "description": "The retrieval policy that surfaced the candidate.",
         "title": "Policy",
         "type": "string"
      },
      "rank": {
         "description": "Rank within the Elasticsearch results (1-based).",
         "title": "Rank",
         "type": "integer"
      },
      "score": {
         "description": "The Elasticsearch relevance score.",
         "title": "Score",
         "type": "number"
      }
   },
   "required": [
      "policy",
      "rank",
      "score"
   ]
}

Fields:

• policy (str)

• rank (int)

• score (float)

• type (Literal['elasticsearch'])

field policy: str [Required]

The retrieval policy that surfaced the candidate.

field rank: int [Required]

Rank within the Elasticsearch results (1-based).

field score: float [Required]

The Elasticsearch relevance score.

field type: Literal['elasticsearch'] = 'elasticsearch'

pydantic model app.domain.references.models.models.CandidateIdentifier

An external identifier used as candidate-search input and match provenance.

Narrows GenericExternalIdentifier to require an explicit type; candidate search does not accept database-id (untyped) lookups.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CandidateIdentifier",
   "description": "An external identifier used as candidate-search input and match provenance.\n\nNarrows :class:`GenericExternalIdentifier` to require an explicit type;\ncandidate search does not accept database-id (untyped) lookups.",
   "type": "object",
   "properties": {
      "identifier": {
         "description": "The identifier itself.",
         "title": "Identifier",
         "type": "string"
      },
      "identifier_type": {
         "$ref": "#/$defs/ExternalIdentifierType",
         "description": "The type of the identifier, e.g. doi, pm_id, open_alex."
      },
      "other_identifier_name": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The name of the other identifier.",
         "title": "Other Identifier Name"
      }
   },
   "$defs": {
      "ExternalIdentifierType": {
         "description": "The type of identifier used to identify a reference.\n\nThis is used to identify the type of identifier used in the `ExternalIdentifier`\nclass.",
         "enum": [
            "doi",
            "eric",
            "pm_id",
            "pro_quest",
            "open_alex",
            "other"
         ],
         "title": "ExternalIdentifierType",
         "type": "string"
      }
   },
   "required": [
      "identifier",
      "identifier_type"
   ]
}

Fields:

• identifier (str)

• identifier_type (destiny_sdk.identifiers.ExternalIdentifierType)

• other_identifier_name (str | None)

field identifier: str [Required]

The identifier itself.

field identifier_type: ExternalIdentifierType [Required]

The type of the identifier, e.g. doi, pm_id, open_alex.

field other_identifier_name: str | None = None

The name of the other identifier.

classmethod from_specific(external_identifier: Annotated[DOIIdentifier | ERICIdentifier | PubMedIdentifier | ProQuestIdentifier | OpenAlexIdentifier | OtherIdentifier, FieldInfo(annotation=NoneType, required=True, discriminator='identifier_type')]) → Self

Create a generic external identifier from a specific implementation.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

pydantic model app.domain.references.models.models.CandidateIdentifierRoute

Provenance for a candidate surfaced by an exact identifier match.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CandidateIdentifierRoute",
   "description": "Provenance for a candidate surfaced by an exact identifier match.",
   "type": "object",
   "properties": {
      "type": {
         "const": "identifier",
         "default": "identifier",
         "title": "Type",
         "type": "string"
      },
      "matched_identifiers": {
         "description": "The input identifiers that matched this candidate.",
         "items": {
            "$ref": "#/$defs/CandidateIdentifier"
         },
         "title": "Matched Identifiers",
         "type": "array"
      }
   },
   "$defs": {
      "CandidateIdentifier": {
         "description": "An external identifier used as candidate-search input and match provenance.\n\nNarrows :class:`GenericExternalIdentifier` to require an explicit type;\ncandidate search does not accept database-id (untyped) lookups.",
         "properties": {
            "identifier": {
               "description": "The identifier itself.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "$ref": "#/$defs/ExternalIdentifierType",
               "description": "The type of the identifier, e.g. doi, pm_id, open_alex."
            },
            "other_identifier_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the other identifier.",
               "title": "Other Identifier Name"
            }
         },
         "required": [
            "identifier",
            "identifier_type"
         ],
         "title": "CandidateIdentifier",
         "type": "object"
      },
      "ExternalIdentifierType": {
         "description": "The type of identifier used to identify a reference.\n\nThis is used to identify the type of identifier used in the `ExternalIdentifier`\nclass.",
         "enum": [
            "doi",
            "eric",
            "pm_id",
            "pro_quest",
            "open_alex",
            "other"
         ],
         "title": "ExternalIdentifierType",
         "type": "string"
      }
   },
   "required": [
      "matched_identifiers"
   ]
}

Fields:

• matched_identifiers (list[app.domain.references.models.models.CandidateIdentifier])

• type (Literal['identifier'])

field matched_identifiers: list[CandidateIdentifier] [Required]

The input identifiers that matched this candidate.

field type: Literal['identifier'] = 'identifier'

pydantic model app.domain.references.models.models.CandidateReference

Hydrated bibliographic fields of a candidate reference.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CandidateReference",
   "description": "Hydrated bibliographic fields of a candidate reference.",
   "type": "object",
   "properties": {
      "title": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Title"
      },
      "authors": {
         "items": {
            "type": "string"
         },
         "title": "Authors",
         "type": "array"
      },
      "publication_year": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Publication Year"
      },
      "identifiers": {
         "items": {
            "$ref": "#/$defs/CandidateIdentifier"
         },
         "title": "Identifiers",
         "type": "array"
      }
   },
   "$defs": {
      "CandidateIdentifier": {
         "description": "An external identifier used as candidate-search input and match provenance.\n\nNarrows :class:`GenericExternalIdentifier` to require an explicit type;\ncandidate search does not accept database-id (untyped) lookups.",
         "properties": {
            "identifier": {
               "description": "The identifier itself.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "$ref": "#/$defs/ExternalIdentifierType",
               "description": "The type of the identifier, e.g. doi, pm_id, open_alex."
            },
            "other_identifier_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the other identifier.",
               "title": "Other Identifier Name"
            }
         },
         "required": [
            "identifier",
            "identifier_type"
         ],
         "title": "CandidateIdentifier",
         "type": "object"
      },
      "ExternalIdentifierType": {
         "description": "The type of identifier used to identify a reference.\n\nThis is used to identify the type of identifier used in the `ExternalIdentifier`\nclass.",
         "enum": [
            "doi",
            "eric",
            "pm_id",
            "pro_quest",
            "open_alex",
            "other"
         ],
         "title": "ExternalIdentifierType",
         "type": "string"
      }
   }
}

Fields:

• authors (list[str])

• identifiers (list[app.domain.references.models.models.CandidateIdentifier])

• publication_year (int | None)

• title (str | None)

field authors: list[str] [Optional]

field identifiers: list[CandidateIdentifier] [Optional]

field publication_year: int | None = None

field title: str | None = None

pydantic model app.domain.references.models.models.CandidateSelectionDiagnostics

Retrieval diagnostics for evaluation.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CandidateSelectionDiagnostics",
   "description": "Retrieval diagnostics for evaluation.",
   "type": "object",
   "properties": {
      "es_took_ms": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Es Took Ms"
      },
      "es_total_hits": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Es Total Hits"
      },
      "es_returned": {
         "default": 0,
         "title": "Es Returned",
         "type": "integer"
      },
      "identifier_returned": {
         "default": 0,
         "title": "Identifier Returned",
         "type": "integer"
      },
      "candidate_count": {
         "default": 0,
         "title": "Candidate Count",
         "type": "integer"
      },
      "truncated": {
         "default": false,
         "title": "Truncated",
         "type": "boolean"
      },
      "kth_es_score": {
         "anyOf": [
            {
               "type": "number"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Kth Es Score"
      },
      "lowest_es_score": {
         "anyOf": [
            {
               "type": "number"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Lowest Es Score"
      }
   }
}

Fields:

• candidate_count (int)

• es_returned (int)

• es_took_ms (int | None)

• es_total_hits (int | None)

• identifier_returned (int)

• kth_es_score (float | None)

• lowest_es_score (float | None)

• truncated (bool)

field candidate_count: int = 0

field es_returned: int = 0

field es_took_ms: int | None = None

field es_total_hits: int | None = None

field identifier_returned: int = 0

field kth_es_score: float | None = None

field lowest_es_score: float | None = None

field truncated: bool = False

pydantic model app.domain.references.models.models.CandidateSelectionInput

The reference to find candidates for.

Provide exactly one of a stored reference_id (projected into search fields server-side) or an inline set of candidate-search fields.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CandidateSelectionInput",
   "description": "The reference to find candidates for.\n\nProvide exactly one of a stored ``reference_id`` (projected into search\nfields server-side) or an inline set of candidate-search fields.",
   "type": "object",
   "properties": {
      "reference_id": {
         "anyOf": [
            {
               "format": "uuid",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "A stored reference to hydrate and project into search fields.",
         "title": "Reference Id"
      },
      "title": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The title to search on.",
         "title": "Title"
      },
      "authors": {
         "description": "The authors to search on.",
         "items": {
            "type": "string"
         },
         "title": "Authors",
         "type": "array"
      },
      "publication_year": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The publication year to search on.",
         "title": "Publication Year"
      },
      "identifiers": {
         "description": "Identifiers to union with the Elasticsearch candidates.",
         "items": {
            "$ref": "#/$defs/CandidateIdentifier"
         },
         "title": "Identifiers",
         "type": "array"
      }
   },
   "$defs": {
      "CandidateIdentifier": {
         "description": "An external identifier used as candidate-search input and match provenance.\n\nNarrows :class:`GenericExternalIdentifier` to require an explicit type;\ncandidate search does not accept database-id (untyped) lookups.",
         "properties": {
            "identifier": {
               "description": "The identifier itself.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "$ref": "#/$defs/ExternalIdentifierType",
               "description": "The type of the identifier, e.g. doi, pm_id, open_alex."
            },
            "other_identifier_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the other identifier.",
               "title": "Other Identifier Name"
            }
         },
         "required": [
            "identifier",
            "identifier_type"
         ],
         "title": "CandidateIdentifier",
         "type": "object"
      },
      "ExternalIdentifierType": {
         "description": "The type of identifier used to identify a reference.\n\nThis is used to identify the type of identifier used in the `ExternalIdentifier`\nclass.",
         "enum": [
            "doi",
            "eric",
            "pm_id",
            "pro_quest",
            "open_alex",
            "other"
         ],
         "title": "ExternalIdentifierType",
         "type": "string"
      }
   }
}

Fields:

• authors (list[str])

• identifiers (list[app.domain.references.models.models.CandidateIdentifier])

• publication_year (int | None)

• reference_id (uuid.UUID | None)

• title (str | None)

Validators:

• validate_exactly_one_input_mode » all fields

field authors: list[str] [Optional]

The authors to search on.

Validated by:

• validate_exactly_one_input_mode

field identifiers: list[CandidateIdentifier] [Optional]

Identifiers to union with the Elasticsearch candidates.

Validated by:

• validate_exactly_one_input_mode

field publication_year: int | None = None

The publication year to search on.

Validated by:

• validate_exactly_one_input_mode

field reference_id: UUID | None = None

A stored reference to hydrate and project into search fields.

Validated by:

• validate_exactly_one_input_mode

field title: str | None = None

The title to search on.

Validated by:

• validate_exactly_one_input_mode

validator validate_exactly_one_input_mode  »  all fields

Require exactly one of reference_id or inline candidate-search fields.

pydantic model app.domain.references.models.models.CandidateSelectionRequest

A request for candidate canonical references, for dedup evaluation.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CandidateSelectionRequest",
   "description": "A request for candidate canonical references, for dedup evaluation.",
   "type": "object",
   "properties": {
      "input": {
         "$ref": "#/$defs/CandidateSelectionInput",
         "description": "The reference to find candidates for."
      },
      "retrieval_policy": {
         "$ref": "#/$defs/RetrievalPolicyName",
         "default": "current_fuzzy_v1",
         "description": "Named, server-side retrieval policy fixing the full candidate regime (query shape, year strategy, identifier union). Defaults to the current fuzzy baseline."
      },
      "k": {
         "anyOf": [
            {
               "maximum": 1000,
               "minimum": 1,
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Number of candidates to retrieve. Defaults to the configured value.",
         "title": "K"
      },
      "hydrate": {
         "default": true,
         "description": "Include hydrated bibliographic fields on each candidate.",
         "title": "Hydrate",
         "type": "boolean"
      },
      "track_total_hits": {
         "default": true,
         "description": "Exact total-hit count (true, past the ES 10k cap) or the Elasticsearch default lower bound (false, as on the nomination path).",
         "title": "Track Total Hits",
         "type": "boolean"
      }
   },
   "$defs": {
      "CandidateIdentifier": {
         "description": "An external identifier used as candidate-search input and match provenance.\n\nNarrows :class:`GenericExternalIdentifier` to require an explicit type;\ncandidate search does not accept database-id (untyped) lookups.",
         "properties": {
            "identifier": {
               "description": "The identifier itself.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "$ref": "#/$defs/ExternalIdentifierType",
               "description": "The type of the identifier, e.g. doi, pm_id, open_alex."
            },
            "other_identifier_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the other identifier.",
               "title": "Other Identifier Name"
            }
         },
         "required": [
            "identifier",
            "identifier_type"
         ],
         "title": "CandidateIdentifier",
         "type": "object"
      },
      "CandidateSelectionInput": {
         "description": "The reference to find candidates for.\n\nProvide exactly one of a stored ``reference_id`` (projected into search\nfields server-side) or an inline set of candidate-search fields.",
         "properties": {
            "reference_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A stored reference to hydrate and project into search fields.",
               "title": "Reference Id"
            },
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The title to search on.",
               "title": "Title"
            },
            "authors": {
               "description": "The authors to search on.",
               "items": {
                  "type": "string"
               },
               "title": "Authors",
               "type": "array"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The publication year to search on.",
               "title": "Publication Year"
            },
            "identifiers": {
               "description": "Identifiers to union with the Elasticsearch candidates.",
               "items": {
                  "$ref": "#/$defs/CandidateIdentifier"
               },
               "title": "Identifiers",
               "type": "array"
            }
         },
         "title": "CandidateSelectionInput",
         "type": "object"
      },
      "ExternalIdentifierType": {
         "description": "The type of identifier used to identify a reference.\n\nThis is used to identify the type of identifier used in the `ExternalIdentifier`\nclass.",
         "enum": [
            "doi",
            "eric",
            "pm_id",
            "pro_quest",
            "open_alex",
            "other"
         ],
         "title": "ExternalIdentifierType",
         "type": "string"
      },
      "RetrievalPolicyName": {
         "description": "Named, versioned candidate-retrieval policies for the Candidate Selection API.\n\nEach value fixes a full retrieval regime (query shape, year strategy,\nidentifier union) under a stable name so recall@K stays comparable across\nruns. A name's semantics never change; a new regime gets a new name.",
         "enum": [
            "current_fuzzy_v1",
            "no_year_filter_v1",
            "no_year_filter_year_optional_v1",
            "soft_year_decay_v1",
            "soft_year_decay_nonfuzzy_probe_v1"
         ],
         "title": "RetrievalPolicyName",
         "type": "string"
      }
   },
   "additionalProperties": false,
   "required": [
      "input"
   ]
}

Config:

• extra: str = forbid

Fields:

• hydrate (bool)

• input (app.domain.references.models.models.CandidateSelectionInput)

• k (int | None)

• retrieval_policy (app.domain.references.models.models.RetrievalPolicyName)

• track_total_hits (bool)

field hydrate: bool = True

Include hydrated bibliographic fields on each candidate.

field input: CandidateSelectionInput [Required]

The reference to find candidates for.

field k: int | None = None

Number of candidates to retrieve. Defaults to the configured value.

Constraints:

• ge = 1

• le = 1000

field retrieval_policy: RetrievalPolicyName = RetrievalPolicyName.CURRENT_FUZZY_V1

Named, server-side retrieval policy fixing the full candidate regime (query shape, year strategy, identifier union). Defaults to the current fuzzy baseline.

field track_total_hits: bool = True

Exact total-hit count (true, past the ES 10k cap) or the Elasticsearch default lower bound (false, as on the nomination path).

pydantic model app.domain.references.models.models.CandidateSelectionResult

Ranked candidates and diagnostics for a candidate-selection request.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CandidateSelectionResult",
   "description": "Ranked candidates and diagnostics for a candidate-selection request.",
   "type": "object",
   "properties": {
      "retrieval_policy": {
         "$ref": "#/$defs/RetrievalPolicyName",
         "default": "current_fuzzy_v1"
      },
      "index_version": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The reference index version the candidates were drawn from.",
         "title": "Index Version"
      },
      "k_requested": {
         "title": "K Requested",
         "type": "integer"
      },
      "input_searchability": {
         "$ref": "#/$defs/InputSearchability"
      },
      "diagnostics": {
         "$ref": "#/$defs/CandidateSelectionDiagnostics"
      },
      "candidates": {
         "items": {
            "$ref": "#/$defs/Candidate"
         },
         "title": "Candidates",
         "type": "array"
      }
   },
   "$defs": {
      "Candidate": {
         "description": "A candidate canonical reference with route provenance.",
         "properties": {
            "reference_id": {
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "rank": {
               "description": "Overall rank across all routes (1-based).",
               "title": "Rank",
               "type": "integer"
            },
            "routes": {
               "description": "How this candidate was surfaced (ES and/or identifier).",
               "items": {
                  "discriminator": {
                     "mapping": {
                        "elasticsearch": "#/$defs/CandidateElasticsearchRoute",
                        "identifier": "#/$defs/CandidateIdentifierRoute"
                     },
                     "propertyName": "type"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/CandidateElasticsearchRoute"
                     },
                     {
                        "$ref": "#/$defs/CandidateIdentifierRoute"
                     }
                  ]
               },
               "title": "Routes",
               "type": "array"
            },
            "reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/CandidateReference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Hydrated bibliographic fields; omitted when hydrate is false."
            }
         },
         "required": [
            "reference_id",
            "rank",
            "routes"
         ],
         "title": "Candidate",
         "type": "object"
      },
      "CandidateElasticsearchRoute": {
         "description": "Provenance for a candidate surfaced by the Elasticsearch query.",
         "properties": {
            "type": {
               "const": "elasticsearch",
               "default": "elasticsearch",
               "title": "Type",
               "type": "string"
            },
            "policy": {
               "description": "The retrieval policy that surfaced the candidate.",
               "title": "Policy",
               "type": "string"
            },
            "rank": {
               "description": "Rank within the Elasticsearch results (1-based).",
               "title": "Rank",
               "type": "integer"
            },
            "score": {
               "description": "The Elasticsearch relevance score.",
               "title": "Score",
               "type": "number"
            }
         },
         "required": [
            "policy",
            "rank",
            "score"
         ],
         "title": "CandidateElasticsearchRoute",
         "type": "object"
      },
      "CandidateIdentifier": {
         "description": "An external identifier used as candidate-search input and match provenance.\n\nNarrows :class:`GenericExternalIdentifier` to require an explicit type;\ncandidate search does not accept database-id (untyped) lookups.",
         "properties": {
            "identifier": {
               "description": "The identifier itself.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "$ref": "#/$defs/ExternalIdentifierType",
               "description": "The type of the identifier, e.g. doi, pm_id, open_alex."
            },
            "other_identifier_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the other identifier.",
               "title": "Other Identifier Name"
            }
         },
         "required": [
            "identifier",
            "identifier_type"
         ],
         "title": "CandidateIdentifier",
         "type": "object"
      },
      "CandidateIdentifierRoute": {
         "description": "Provenance for a candidate surfaced by an exact identifier match.",
         "properties": {
            "type": {
               "const": "identifier",
               "default": "identifier",
               "title": "Type",
               "type": "string"
            },
            "matched_identifiers": {
               "description": "The input identifiers that matched this candidate.",
               "items": {
                  "$ref": "#/$defs/CandidateIdentifier"
               },
               "title": "Matched Identifiers",
               "type": "array"
            }
         },
         "required": [
            "matched_identifiers"
         ],
         "title": "CandidateIdentifierRoute",
         "type": "object"
      },
      "CandidateReference": {
         "description": "Hydrated bibliographic fields of a candidate reference.",
         "properties": {
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Title"
            },
            "authors": {
               "items": {
                  "type": "string"
               },
               "title": "Authors",
               "type": "array"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Publication Year"
            },
            "identifiers": {
               "items": {
                  "$ref": "#/$defs/CandidateIdentifier"
               },
               "title": "Identifiers",
               "type": "array"
            }
         },
         "title": "CandidateReference",
         "type": "object"
      },
      "CandidateSelectionDiagnostics": {
         "description": "Retrieval diagnostics for evaluation.",
         "properties": {
            "es_took_ms": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Es Took Ms"
            },
            "es_total_hits": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Es Total Hits"
            },
            "es_returned": {
               "default": 0,
               "title": "Es Returned",
               "type": "integer"
            },
            "identifier_returned": {
               "default": 0,
               "title": "Identifier Returned",
               "type": "integer"
            },
            "candidate_count": {
               "default": 0,
               "title": "Candidate Count",
               "type": "integer"
            },
            "truncated": {
               "default": false,
               "title": "Truncated",
               "type": "boolean"
            },
            "kth_es_score": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Kth Es Score"
            },
            "lowest_es_score": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Lowest Es Score"
            }
         },
         "title": "CandidateSelectionDiagnostics",
         "type": "object"
      },
      "ExternalIdentifierType": {
         "description": "The type of identifier used to identify a reference.\n\nThis is used to identify the type of identifier used in the `ExternalIdentifier`\nclass.",
         "enum": [
            "doi",
            "eric",
            "pm_id",
            "pro_quest",
            "open_alex",
            "other"
         ],
         "title": "ExternalIdentifierType",
         "type": "string"
      },
      "InputSearchability": {
         "description": "Whether the input meets the Elasticsearch bibliographic searchability gate.",
         "properties": {
            "searchable": {
               "description": "Whether the input meets the Elasticsearch searchability gate (title, authors, and publication year unless the selected retrieval policy makes it optional). Exact identifier matching runs regardless, so candidates may be present even when this is false.",
               "title": "Searchable",
               "type": "boolean"
            },
            "reason": {
               "description": "Explanation of the searchability decision.",
               "title": "Reason",
               "type": "string"
            }
         },
         "required": [
            "searchable",
            "reason"
         ],
         "title": "InputSearchability",
         "type": "object"
      },
      "RetrievalPolicyName": {
         "description": "Named, versioned candidate-retrieval policies for the Candidate Selection API.\n\nEach value fixes a full retrieval regime (query shape, year strategy,\nidentifier union) under a stable name so recall@K stays comparable across\nruns. A name's semantics never change; a new regime gets a new name.",
         "enum": [
            "current_fuzzy_v1",
            "no_year_filter_v1",
            "no_year_filter_year_optional_v1",
            "soft_year_decay_v1",
            "soft_year_decay_nonfuzzy_probe_v1"
         ],
         "title": "RetrievalPolicyName",
         "type": "string"
      }
   },
   "required": [
      "k_requested",
      "input_searchability",
      "diagnostics"
   ]
}

Fields:

• candidates (list[app.domain.references.models.models.Candidate])

• diagnostics (app.domain.references.models.models.CandidateSelectionDiagnostics)

• index_version (str | None)

• input_searchability (app.domain.references.models.models.InputSearchability)

• k_requested (int)

• retrieval_policy (app.domain.references.models.models.RetrievalPolicyName)

field candidates: list[Candidate] [Optional]

field diagnostics: CandidateSelectionDiagnostics [Required]

field index_version: str | None = None

The reference index version the candidates were drawn from.

field input_searchability: InputSearchability [Required]

field k_requested: int [Required]

field retrieval_policy: RetrievalPolicyName = RetrievalPolicyName.CURRENT_FUZZY_V1

pydantic model app.domain.references.models.models.CrossFacetAxis

One resolved axis of a cross-facet aggregation.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CrossFacetAxis",
   "description": "One resolved axis of a cross-facet aggregation.",
   "type": "object",
   "properties": {
      "token": {
         "description": "The original axis request string (literal or scheme URI).",
         "title": "Token",
         "type": "string"
      },
      "facet_type": {
         "$ref": "#/$defs/FacetType",
         "description": "The facet whose field this axis aggregates on."
      },
      "include": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array",
               "uniqueItems": true
            },
            {
               "type": "null"
            }
         ],
         "description": "The concept URIs scoping a scheme axis (used as the terms ``include`` set). ``None`` for other axes, whose field domain is bounded.",
         "title": "Include"
      },
      "size": {
         "description": "The terms ``size`` to request for this axis's bucket count.",
         "exclusiveMinimum": 0,
         "title": "Size",
         "type": "integer"
      }
   },
   "$defs": {
      "FacetType": {
         "description": "A facet supported by the reference search facets endpoint.",
         "enum": [
            "concepts",
            "countries",
            "country_wb_regions"
         ],
         "title": "FacetType",
         "type": "string"
      }
   },
   "required": [
      "token",
      "facet_type",
      "include",
      "size"
   ]
}

Config:

• frozen: bool = True

Fields:

• facet_type (app.domain.references.models.models.FacetType)

• include (frozenset[str] | None)

• size (int)

• token (str)

field facet_type: FacetType [Required]

The facet whose field this axis aggregates on.

field include: frozenset[str] | None [Required]

The concept URIs scoping a scheme axis (used as the terms include set). None for other axes, whose field domain is bounded.

field size: int [Required]

The terms size to request for this axis’s bucket count.

Constraints:

• gt = 0

field token: str [Required]

The original axis request string (literal or scheme URI).

pydantic model app.domain.references.models.models.CrossFacetCell

A single non-zero cell of a cross-facet matrix.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CrossFacetCell",
   "description": "A single non-zero cell of a cross-facet matrix.",
   "type": "object",
   "properties": {
      "axes": {
         "description": "The cell's value on each axis, in requested axis order.",
         "maxItems": 2,
         "minItems": 2,
         "prefixItems": [
            {
               "type": "string"
            },
            {
               "type": "string"
            }
         ],
         "title": "Axes",
         "type": "array"
      },
      "count": {
         "description": "References matching both axis values together.",
         "title": "Count",
         "type": "integer"
      }
   },
   "required": [
      "axes",
      "count"
   ]
}

Fields:

• axes (tuple[str, str])

• count (int)

field axes: tuple[str, str] [Required]

The cell’s value on each axis, in requested axis order.

field count: int [Required]

References matching both axis values together.

class app.domain.references.models.models.DuplicateDetermination(*values)

The determination of whether a reference is a duplicate.

This encodes both a status and a determination.

CANONICAL = 'canonical'

[TERMINAL] The reference is not a duplicate of another reference.

DECOUPLED = 'decoupled'

A decision has been made, but needs further attention. This could be due to a change in the canonical mapping, or a reference with existing duplicates being marked as a duplicate.

DUPLICATE = 'duplicate'

[TERMINAL] The reference is a duplicate of another reference.

EXACT_DUPLICATE = 'exact_duplicate'

[TERMINAL] The reference is an identical subset of another reference and has been removed. This is rare and generally occurs in repeated imports.

NOMINATED = 'nominated'

Candidate canonicals have been identified for the reference and it is being further deduplicated.

PENDING = 'pending'

The duplicate status is still being determined.

UNRESOLVED = 'unresolved'

Automatic attempts to resolve the duplicate were unsuccessful.

UNSEARCHABLE = 'unsearchable'

[TERMINAL] The reference does not have sufficient metadata to be automatically matched to other references, or the duplicate detection process has been explicitly disabled.

classmethod get_terminal_states() → set[DuplicateDetermination]

Return the set of terminal DuplicateDetermination states.

pydantic model app.domain.references.models.models.Enhancement

Core enhancement model with database attributes included.

Show Entity Relationship Diagram

Show JSON schema

{
   "$defs": {
      "AbstractContentEnhancement": {
         "description": "An enhancement which is specific to the abstract of a reference.\n\nThis is separate from the `BibliographicMetadata` for two reasons:\n\n1. Abstracts are increasingly missing from sources like OpenAlex, and may be\nbackfilled from other sources, without the bibliographic metadata.\n2. They are also subject to copyright limitations in ways which metadata are\nnot, and thus need separate visibility controls.",
         "properties": {
            "enhancement_type": {
               "const": "abstract",
               "default": "abstract",
               "title": "Enhancement Type",
               "type": "string"
            },
            "process": {
               "$ref": "#/$defs/AbstractProcessType"
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquire the abstract.",
         "enum": [
            "uninverted",
            "closed_api",
            "other"
         ],
         "title": "AbstractProcessType",
         "type": "string"
      },
      "AnnotationEnhancement": {
         "description": "An enhancement which is composed of a list of Annotations.",
         "properties": {
            "enhancement_type": {
               "const": "annotation",
               "default": "annotation",
               "title": "Enhancement Type",
               "type": "string"
            },
            "annotations": {
               "items": {
                  "discriminator": {
                     "mapping": {
                        "boolean": "#/$defs/BooleanAnnotation",
                        "score": "#/$defs/ScoreAnnotation"
                     },
                     "propertyName": "annotation_type"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/BooleanAnnotation"
                     },
                     {
                        "$ref": "#/$defs/ScoreAnnotation"
                     }
                  ]
               },
               "minItems": 1,
               "title": "Annotations",
               "type": "array"
            }
         },
         "required": [
            "annotations"
         ],
         "title": "AnnotationEnhancement",
         "type": "object"
      },
      "AuthorPosition": {
         "description": "The position of an author in a list of authorships.\n\nMaps to the data from OpenAlex.",
         "enum": [
            "first",
            "middle",
            "last"
         ],
         "title": "AuthorPosition",
         "type": "string"
      },
      "Authorship": {
         "description": "Represents a single author and their association with a reference.\n\nThis is a simplification of the OpenAlex [Authorship\nobject](https://docs.openalex.org/api-entities/works/work-object/authorship-object)\nfor our purposes.",
         "properties": {
            "display_name": {
               "description": "The display name of the author. Expected format FIRSTNAME <MIDDLENAME> LASTNAME. Providing display_name in an unexpected format will affect search performance.",
               "title": "Display Name",
               "type": "string"
            },
            "orcid": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ORCid of the author.",
               "title": "Orcid"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "position"
         ],
         "title": "Authorship",
         "type": "object"
      },
      "BibliographicMetadataEnhancement": {
         "description": "An enhancement which is made up of bibliographic metadata.\n\nGenerally this will be sourced from a database such as OpenAlex or similar.\nFor directly contributed references, these may not be complete.",
         "properties": {
            "enhancement_type": {
               "const": "bibliographic",
               "default": "bibliographic",
               "title": "Enhancement Type",
               "type": "string"
            },
            "authorship": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Authorship"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `Authorships` belonging to this reference.",
               "title": "Authorship"
            },
            "cited_by_count": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex) The number of citations to this work. These are the times that\nother works have cited this work\n",
               "title": "Cited By Count"
            },
            "created_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date this metadata record was created",
               "title": "Created Date"
            },
            "updated_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date of the last OpenAlex update to this metadata",
               "title": "Updated Date"
            },
            "publication_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The date which the version of record was published.",
               "title": "Publication Date"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The year in which the version of record was published.",
               "title": "Publication Year"
            },
            "publisher": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the entity which published the version of record.",
               "title": "Publisher"
            },
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The title of the reference.",
               "title": "Title"
            },
            "pagination": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Pagination"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Pagination info (volume, issue, pages)."
            },
            "publication_venue": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenue"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Publication venue information (journal, repository, etc.)."
            }
         },
         "title": "BibliographicMetadataEnhancement",
         "type": "object"
      },
      "BlobStorageFile": {
         "description": "Model to represent Blob Storage files.",
         "properties": {
            "location": {
               "$ref": "#/$defs/BlobStorageLocation",
               "description": "The location of the blob storage."
            },
            "container": {
               "description": "The name of the container in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in blob storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio",
            "http",
            "https"
         ],
         "title": "BlobStorageLocation",
         "type": "string"
      },
      "BooleanAnnotation": {
         "description": "An annotation is a way of tagging the content with a label of some kind.\n\nThis class will probably be broken up in the future, but covers most of our\ninitial cases.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "value": {
               "description": "Boolean flag for this annotation",
               "title": "Value",
               "type": "boolean"
            },
            "score": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A confidence score for this annotation",
               "title": "Score"
            },
            "data": {
               "additionalProperties": true,
               "description": "\nAn object representation of the annotation including any confidence scores or\ndescriptions.\n",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "value"
         ],
         "title": "BooleanAnnotation",
         "type": "object"
      },
      "DOIIdentifier": {
         "description": "An external identifier representing a DOI.",
         "properties": {
            "identifier": {
               "description": "The DOI of the reference. Format: '10.<registrant>/<suffix>' where registrant is 4-9 digits and suffix is any non-whitespace characters. Examples: 10.1000/journal.pone.0001, 10.18730/9WQ$D, 10.1000/\u00e9dition",
               "pattern": "^10\\.\\d{4,9}/\\S+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "doi",
               "default": "doi",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "DOIIdentifier",
         "type": "object"
      },
      "DriverVersion": {
         "description": "The version based on the DRIVER guidelines versioning scheme.\n\n(Borrowed from OpenAlex)",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "type": "string"
      },
      "DuplicateDetermination": {
         "description": "The determination of whether a reference is a duplicate.\n\nThis encodes both a status and a determination.",
         "enum": [
            "pending",
            "nominated",
            "duplicate",
            "exact_duplicate",
            "canonical",
            "unresolved",
            "unsearchable",
            "decoupled"
         ],
         "title": "DuplicateDetermination",
         "type": "string"
      },
      "ERICIdentifier": {
         "description": "An external identifier representing an ERIC Number.\n\nAn ERIC Number is defined as a unique identifying number preceded by\nED (for a non-journal document) or EJ (for a journal article).",
         "properties": {
            "identifier": {
               "description": "The ERIC Number. Format: 'ED' or 'EJ' followed by digits. Example: ED123456 or EJ789012",
               "pattern": "E[D|J][0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "eric",
               "default": "eric",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ERICIdentifier",
         "type": "object"
      },
      "Enhancement": {
         "description": "Core enhancement model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "created_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp at which the object was created.",
               "title": "Created At"
            },
            "updated_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp at which the object was last updated.",
               "title": "Updated At"
            },
            "source": {
               "description": "The enhancement source for tracking provenance.",
               "title": "Source",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "description": "The level of visibility of the enhancement"
            },
            "robot_version": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version of the robot that generated the content.",
               "title": "Robot Version"
            },
            "derived_from": {
               "anyOf": [
                  {
                     "items": {
                        "format": "uuid",
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of enhancement IDs that this enhancement was derived from.",
               "title": "Derived From"
            },
            "content": {
               "description": "The content of the enhancement.",
               "discriminator": {
                  "mapping": {
                     "abstract": "#/$defs/AbstractContentEnhancement",
                     "annotation": "#/$defs/AnnotationEnhancement",
                     "bibliographic": "#/$defs/BibliographicMetadataEnhancement",
                     "full_text": "#/$defs/FullTextEnhancement",
                     "linked_data": "#/$defs/LinkedDataEnhancement",
                     "location": "#/$defs/LocationEnhancement",
                     "raw": "#/$defs/RawEnhancement",
                     "reference_association": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LinkedDataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/FullTextEnhancement"
                  },
                  {
                     "$ref": "#/$defs/RawEnhancement"
                  }
               ],
               "title": "Content"
            },
            "reference_id": {
               "description": "The ID of the reference this enhancement is associated with.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The reference this enhancement is associated with."
            }
         },
         "required": [
            "source",
            "visibility",
            "content",
            "reference_id"
         ],
         "title": "Enhancement",
         "type": "object"
      },
      "FullTextEnhancement": {
         "description": "An enhancement for storing a link to the full text and its metadata.\n\nWe separate this from the SDK model as it contains a file pointer, not\nthe URL to the file itself.",
         "properties": {
            "enhancement_type": {
               "const": "full_text",
               "default": "full_text",
               "title": "Enhancement Type",
               "type": "string"
            },
            "blob": {
               "$ref": "#/$defs/BlobStorageFile",
               "description": "Blob storage pointer to the full text file."
            },
            "byte_size": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Size of the file in bytes. If provided on import, will be used to validate the file size. Will always be present on enhancements from the repository.",
               "title": "Byte Size"
            },
            "sha256_checksum": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "SHA256 checksum of the file. If provided on import, will be used to verify the integrity of the file. Will always be present on enhancements from the repository.",
               "title": "Sha256 Checksum"
            },
            "mime_type": {
               "default": "application/pdf",
               "description": "The MIME type of the file.",
               "title": "Mime Type",
               "type": "string"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version (according to the DRIVER versioning scheme) of this full text."
            },
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "If this full text is Open Access. May be left as null if this is unknown.",
               "title": "Is Oa"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The publishing license for this full text.",
               "examples": [
                  "apache-2-0",
                  "cc-by",
                  "cc-by-nc",
                  "cc-by-nc-nd",
                  "cc-by-nc-sa",
                  "cc-by-nd",
                  "cc-by-sa",
                  "gpl-v2",
                  "gpl-v3",
                  "isc",
                  "mit",
                  "other-oa",
                  "public-domain"
               ],
               "title": "License"
            },
            "source": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The source from which this full text was obtained.",
               "title": "Source"
            },
            "source_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The URL of the source from which this full text was obtained.",
               "title": "Source Url"
            },
            "retrieved_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp when this full text was retrieved.",
               "title": "Retrieved At"
            }
         },
         "required": [
            "blob"
         ],
         "title": "FullTextEnhancement",
         "type": "object"
      },
      "JsonValue": {},
      "LinkedDataEnhancement": {
         "description": "An enhancement for storing structured data in a linked data format.\n\nThe content is a JSON-LD document conforming to the vocabulary and\ncontext specified. This enhancement type is produced by mapping robots\nthat transform RawEnhancement data into the shared vocabulary.",
         "properties": {
            "enhancement_type": {
               "const": "linked_data",
               "default": "linked_data",
               "title": "Enhancement Type",
               "type": "string"
            },
            "vocabulary_uri": {
               "description": "The URI of the vocabulary against which this data was produced. Used for compatibility checking.",
               "examples": [
                  "https://vocab.evrepo.org/vocabulary/v1"
               ],
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "Vocabulary Uri",
               "type": "string"
            },
            "data": {
               "additionalProperties": {
                  "$ref": "#/$defs/JsonValue"
               },
               "description": "The JSON-LD content. Must contain an '@context' key with a valid URI string. When combined with the @context, this forms a complete linked data graph.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "vocabulary_uri",
            "data"
         ],
         "title": "LinkedDataEnhancement",
         "type": "object"
      },
      "LinkedExternalIdentifier": {
         "description": "External identifier model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "identifier": {
               "description": "The identifier itself.",
               "discriminator": {
                  "mapping": {
                     "doi": "#/$defs/DOIIdentifier",
                     "eric": "#/$defs/ERICIdentifier",
                     "open_alex": "#/$defs/OpenAlexIdentifier",
                     "other": "#/$defs/OtherIdentifier",
                     "pm_id": "#/$defs/PubMedIdentifier",
                     "pro_quest": "#/$defs/ProQuestIdentifier"
                  },
                  "propertyName": "identifier_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/DOIIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ERICIdentifier"
                  },
                  {
                     "$ref": "#/$defs/PubMedIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ProQuestIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OpenAlexIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OtherIdentifier"
                  }
               ],
               "title": "Identifier"
            },
            "reference_id": {
               "description": "The ID of the reference this identifier identifies.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The reference this identifier identifies."
            }
         },
         "required": [
            "identifier",
            "reference_id"
         ],
         "title": "LinkedExternalIdentifier",
         "type": "object"
      },
      "Location": {
         "description": "A location where a reference can be found.\n\nThis maps almost completely to the OpenAlex\n[Location object](https://docs.openalex.org/api-entities/works/work-object/location-object)",
         "properties": {
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): True if an Open Access (OA) version of this work is available\nat this location. May be left as null if this is unknown (and thus)\ntreated effectively as `false`.\n",
               "title": "Is Oa"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\nThe version (according to the DRIVER versioning scheme) of this location.\n"
            },
            "landing_page_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "(From OpenAlex): The landing page URL for this location.",
               "title": "Landing Page Url"
            },
            "pdf_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): A URL where you can find this location as a PDF.\n",
               "title": "Pdf Url"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): The location's publishing license. This can be a Creative\nCommons license such as cc0 or cc-by, a publisher-specific license, or null\nwhich means we are not able to determine a license for this location.\n",
               "title": "License"
            },
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Any extra metadata about this location",
               "title": "Extra"
            }
         },
         "title": "Location",
         "type": "object"
      },
      "LocationEnhancement": {
         "description": "An enhancement which describes locations where this reference can be found.\n\nThis maps closely (almost exactly) to OpenAlex's locations.",
         "properties": {
            "enhancement_type": {
               "const": "location",
               "default": "location",
               "title": "Enhancement Type",
               "type": "string"
            },
            "locations": {
               "description": "A list of locations where this reference can be found.",
               "items": {
                  "$ref": "#/$defs/Location"
               },
               "minItems": 1,
               "title": "Locations",
               "type": "array"
            }
         },
         "required": [
            "locations"
         ],
         "title": "LocationEnhancement",
         "type": "object"
      },
      "OpenAlexIdentifier": {
         "description": "An external identifier representing an OpenAlex ID.",
         "properties": {
            "identifier": {
               "description": "The OpenAlex ID of the reference. Format: 'W' followed by digits. Example: W2741809807",
               "pattern": "^W\\d+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "open_alex",
               "default": "open_alex",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "OpenAlexIdentifier",
         "type": "object"
      },
      "OtherIdentifier": {
         "description": "An external identifier not otherwise defined by the repository.",
         "properties": {
            "identifier": {
               "description": "The identifier of the reference.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "other",
               "default": "other",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            },
            "other_identifier_name": {
               "description": "The name of the undocumented identifier type.",
               "title": "Other Identifier Name",
               "type": "string"
            }
         },
         "required": [
            "identifier",
            "other_identifier_name"
         ],
         "title": "OtherIdentifier",
         "type": "object"
      },
      "Pagination": {
         "description": "Pagination information for journal articles.\n\nMaps to OpenAlex's work.biblio object. All fields are strings to match\nOpenAlex's format, which may include non-numeric values like \"Spring\" or \"A1\".",
         "properties": {
            "volume": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The volume number of the journal/publication.",
               "title": "Volume"
            },
            "issue": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The issue number of the journal/publication.",
               "title": "Issue"
            },
            "first_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The first page number of the reference in the publication.",
               "title": "First Page"
            },
            "last_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The last page number of the reference in the publication.",
               "title": "Last Page"
            }
         },
         "title": "Pagination",
         "type": "object"
      },
      "ProQuestIdentifier": {
         "description": "An external identifier representing a ProQuest ID.",
         "properties": {
            "identifier": {
               "description": "The ProQuest ID of the reference. Format: numeric digits only. Example: 12345678",
               "pattern": "[0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "pro_quest",
               "default": "pro_quest",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ProQuestIdentifier",
         "type": "object"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID (PMID) of the reference. Example: 12345678",
               "exclusiveMinimum": 0,
               "title": "Identifier",
               "type": "integer"
            },
            "identifier_type": {
               "const": "pm_id",
               "default": "pm_id",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "PubMedIdentifier",
         "type": "object"
      },
      "PublicationVenue": {
         "description": "A publication venue (journal, repository, conference, etc.).",
         "properties": {
            "display_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The display name of the venue (journal name, repository name, etc.)",
               "title": "Display Name"
            },
            "venue_type": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenueType"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The type of venue: journal, repository, book, conference, etc."
            },
            "issn": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of ISSNs associated with this venue (print and electronic)",
               "title": "Issn"
            },
            "issn_l": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The linking ISSN - a canonical ISSN for the venue across format changes",
               "title": "Issn L"
            },
            "host_organization_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Display name of the host organization (publisher)",
               "title": "Host Organization Name"
            }
         },
         "title": "PublicationVenue",
         "type": "object"
      },
      "PublicationVenueType": {
         "description": "Type of publication venue.\n\nAligns with OpenAlex source types.",
         "enum": [
            "journal",
            "repository",
            "conference",
            "ebook_platform",
            "book_series",
            "other"
         ],
         "title": "PublicationVenueType",
         "type": "string"
      },
      "RawEnhancement": {
         "description": "An enhancement for storing raw/arbitrary/unstructured data.\n\nData in these enhancements is intended for future conversion into structured form.\n\nThis enhancement accepts any fields passed in to `data`. These enhancements cannot\nbe created by robots.",
         "properties": {
            "enhancement_type": {
               "const": "raw",
               "default": "raw",
               "title": "Enhancement Type",
               "type": "string"
            },
            "source_export_date": {
               "description": "Date the enhancement data was retrieved.",
               "format": "date-time",
               "title": "Source Export Date",
               "type": "string"
            },
            "description": {
               "description": "Description of the data to aid in future refinement.",
               "title": "Description",
               "type": "string"
            },
            "metadata": {
               "additionalProperties": true,
               "description": "Additional metadata to aid in future structuring of raw data",
               "title": "Metadata",
               "type": "object"
            },
            "data": {
               "description": "Unstructured data for later processing.",
               "title": "Data"
            }
         },
         "required": [
            "source_export_date",
            "description",
            "data"
         ],
         "title": "RawEnhancement",
         "type": "object"
      },
      "Reference": {
         "description": "Core reference model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "default": "public",
               "description": "The level of visibility of the reference"
            },
            "identifiers": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/LinkedExternalIdentifier"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `LinkedExternalIdentifiers` for the Reference",
               "title": "Identifiers"
            },
            "enhancements": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Enhancement"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of enhancements for the reference",
               "title": "Enhancements"
            },
            "duplicate_decision": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/ReferenceDuplicateDecision"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The current active duplicate decision for this reference. If None, either duplicate_decision has not been preloaded or the duplicate status is pending."
            },
            "canonical_reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The canonical reference that this reference is a duplicate of"
            },
            "duplicate_references": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Reference"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of references that this reference duplicates",
               "title": "Duplicate References"
            }
         },
         "title": "Reference",
         "type": "object"
      },
      "ReferenceAssociationEnhancement": {
         "description": "An enhancement for storing associations between references.",
         "properties": {
            "enhancement_type": {
               "const": "reference_association",
               "default": "reference_association",
               "title": "Enhancement Type",
               "type": "string"
            },
            "associated_reference_ids": {
               "description": "A list of Identifiers which are associated to this reference. These can either be ExternalIdentifiers or resolved repository UUID4s.",
               "items": {
                  "anyOf": [
                     {
                        "discriminator": {
                           "mapping": {
                              "doi": "#/$defs/DOIIdentifier",
                              "eric": "#/$defs/ERICIdentifier",
                              "open_alex": "#/$defs/OpenAlexIdentifier",
                              "other": "#/$defs/OtherIdentifier",
                              "pm_id": "#/$defs/PubMedIdentifier",
                              "pro_quest": "#/$defs/ProQuestIdentifier"
                           },
                           "propertyName": "identifier_type"
                        },
                        "oneOf": [
                           {
                              "$ref": "#/$defs/DOIIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ERICIdentifier"
                           },
                           {
                              "$ref": "#/$defs/PubMedIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ProQuestIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OpenAlexIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OtherIdentifier"
                           }
                        ]
                     },
                     {
                        "anyOf": [
                           {
                              "format": "uuid4",
                              "type": "string"
                           },
                           {
                              "format": "uuid7",
                              "type": "string"
                           }
                        ],
                        "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
                     }
                  ]
               },
               "minItems": 1,
               "title": "Associated Reference Ids",
               "type": "array"
            },
            "association_type": {
               "$ref": "#/$defs/ReferenceAssociationType",
               "description": "The type of association between this reference and the associated ones. Direction is important: \"this reference <association_type> associated reference\"."
            }
         },
         "required": [
            "associated_reference_ids",
            "association_type"
         ],
         "title": "ReferenceAssociationEnhancement",
         "type": "object"
      },
      "ReferenceAssociationType": {
         "description": "The type of association between references.\n\nDirection is important: \"this reference <association_type> associated reference\".",
         "enum": [
            "cites",
            "is_cited_by",
            "is_similar_to"
         ],
         "title": "ReferenceAssociationType",
         "type": "string"
      },
      "ReferenceDuplicateDecision": {
         "description": "Model representing a decision on whether a reference is a duplicate.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "reference_id": {
               "description": "The ID of the reference being evaluated.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "enhancement_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the enhancement that triggered this duplicate decision, if any.",
               "title": "Enhancement Id"
            },
            "active_decision": {
               "default": false,
               "description": "Whether this is the active decision for the reference.",
               "title": "Active Decision",
               "type": "boolean"
            },
            "candidate_canonical_ids": {
               "description": "A list of candidate canonical IDs for the reference.",
               "items": {
                  "format": "uuid",
                  "type": "string"
               },
               "title": "Candidate Canonical Ids",
               "type": "array"
            },
            "duplicate_determination": {
               "$ref": "#/$defs/DuplicateDetermination",
               "default": "pending",
               "description": "The duplicate status of the reference."
            },
            "canonical_reference_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the canonical reference this reference duplicates.",
               "title": "Canonical Reference Id"
            },
            "detail": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Optional additional detail about the decision.",
               "title": "Detail"
            }
         },
         "required": [
            "reference_id"
         ],
         "title": "ReferenceDuplicateDecision",
         "type": "object"
      },
      "ScoreAnnotation": {
         "description": "An annotation which represents the score for a label.\n\nThis is similar to a BooleanAnnotation, but lacks a boolean determination\nas to the application of the label.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "score": {
               "description": "Score for this annotation",
               "title": "Score",
               "type": "number"
            },
            "data": {
               "additionalProperties": true,
               "description": "An object representation of the annotation including any confidence scores or descriptions.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "score"
         ],
         "title": "ScoreAnnotation",
         "type": "object"
      },
      "Visibility": {
         "description": "The visibility of a data element in the repository.\n\nThis is used to manage whether information should be publicly available or\nrestricted (generally due to copyright constraints from publishers).\n\nTODO: Implement data governance layer to manage this.",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   },
   "$ref": "#/$defs/Enhancement"
}

Config:

• from_attributes: bool = True

Fields:

• content (destiny_sdk.enhancements.BibliographicMetadataEnhancement | destiny_sdk.enhancements.AbstractContentEnhancement | destiny_sdk.enhancements.AnnotationEnhancement | destiny_sdk.enhancements.LocationEnhancement | destiny_sdk.enhancements.ReferenceAssociationEnhancement | destiny_sdk.enhancements.LinkedDataEnhancement | app.domain.references.models.models.FullTextEnhancement | destiny_sdk.enhancements.RawEnhancement)

• created_at (datetime.datetime | None)

• derived_from (list[uuid.UUID] | None)

• id (uuid.UUID)

• reference (app.domain.references.models.models.Reference | None)

• reference_id (uuid.UUID)

• robot_version (str | None)

• source (str)

• updated_at (datetime.datetime | None)

• visibility (app.domain.references.models.models.Visibility)

field content: Annotated[BibliographicMetadataEnhancement | AbstractContentEnhancement | AnnotationEnhancement | LocationEnhancement | ReferenceAssociationEnhancement | LinkedDataEnhancement | FullTextEnhancement | RawEnhancement, FieldInfo(annotation=NoneType, required=True, discriminator='enhancement_type')] [Required]

The content of the enhancement.

field created_at: datetime.datetime | None = None

The timestamp at which the object was created.

field derived_from: list[UUID] | None = None

List of enhancement IDs that this enhancement was derived from.

field id: UUID [Optional]

The autogenerated database ID.

field reference: Reference | None = None

The reference this enhancement is associated with.

field reference_id: UUID [Required]

The ID of the reference this enhancement is associated with.

field robot_version: str | None = None

The version of the robot that generated the content.

field source: str [Required]

The enhancement source for tracking provenance.

field updated_at: datetime.datetime | None = None

The timestamp at which the object was last updated.

field visibility: Visibility [Required]

The level of visibility of the enhancement

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

hash_data() → int

Contentwise hash of the enhancement.

Excludes relationships and timestamps.

pydantic model app.domain.references.models.models.EnhancementRequest

Request to add enhancements to a list of references.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "EnhancementRequest",
   "description": "Request to add enhancements to a list of references.",
   "type": "object",
   "properties": {
      "id": {
         "description": "The autogenerated database ID.",
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "reference_ids": {
         "description": "The IDs of the references these enhancements are associated with.",
         "items": {
            "format": "uuid",
            "type": "string"
         },
         "title": "Reference Ids",
         "type": "array"
      },
      "robot_id": {
         "description": "The robot to request the enhancement from.",
         "format": "uuid",
         "title": "Robot Id",
         "type": "string"
      },
      "request_status": {
         "$ref": "#/$defs/EnhancementRequestStatus",
         "default": "received",
         "description": "The status of the request to create an enhancement."
      },
      "source": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The source of the batch enhancement request.",
         "title": "Source"
      },
      "enhancement_parameters": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional optional parameters to pass through to the robot.",
         "title": "Enhancement Parameters"
      },
      "error": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "\nProcedural error affecting all references encountered during the enhancement process.\nErrors for individual references are provided <TBC>.\n",
         "title": "Error"
      },
      "reference_data_file": {
         "anyOf": [
            {
               "$ref": "#/$defs/BlobStorageFile"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The file containing the reference data for the robot."
      },
      "result_file": {
         "anyOf": [
            {
               "$ref": "#/$defs/BlobStorageFile"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The file containing the result data from the robot."
      },
      "validation_result_file": {
         "anyOf": [
            {
               "$ref": "#/$defs/BlobStorageFile"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The file containing the validation result data from the robot."
      },
      "pending_enhancements": {
         "anyOf": [
            {
               "items": {
                  "$ref": "#/$defs/PendingEnhancement"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "List of pending enhancements for the request.",
         "title": "Pending Enhancements"
      }
   },
   "$defs": {
      "BlobStorageFile": {
         "description": "Model to represent Blob Storage files.",
         "properties": {
            "location": {
               "$ref": "#/$defs/BlobStorageLocation",
               "description": "The location of the blob storage."
            },
            "container": {
               "description": "The name of the container in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in blob storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio",
            "http",
            "https"
         ],
         "title": "BlobStorageLocation",
         "type": "string"
      },
      "EnhancementRequestStatus": {
         "description": "The status of an enhancement request.",
         "enum": [
            "received",
            "accepted",
            "processing",
            "rejected",
            "partial_failed",
            "failed",
            "importing",
            "indexing",
            "indexing_failed",
            "completed"
         ],
         "title": "EnhancementRequestStatus",
         "type": "string"
      },
      "PendingEnhancement": {
         "description": "A pending enhancement.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "reference_id": {
               "description": "The ID of the reference to be enhanced.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "robot_id": {
               "description": "The ID of the robot that will perform the enhancement.",
               "format": "uuid",
               "title": "Robot Id",
               "type": "string"
            },
            "enhancement_request_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the batch enhancement request that this pending enhancement belongs to.",
               "title": "Enhancement Request Id"
            },
            "robot_enhancement_batch_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the robot enhancement batch that this pending enhancement belongs to.",
               "title": "Robot Enhancement Batch Id"
            },
            "status": {
               "$ref": "#/$defs/PendingEnhancementStatus",
               "default": "pending",
               "description": "The status of the pending enhancement."
            },
            "source": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The source of the pending enhancement for provenance tracking, if not an enhancement request.",
               "title": "Source"
            },
            "expires_at": {
               "default": "1970-01-01T00:00:00Z",
               "description": "The datetime at which the pending enhancement expires.",
               "format": "date-time",
               "title": "Expires At",
               "type": "string"
            },
            "retry_of": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the pending enhancement that this is a retry of, if any.",
               "title": "Retry Of"
            }
         },
         "required": [
            "reference_id",
            "robot_id"
         ],
         "title": "PendingEnhancement",
         "type": "object"
      },
      "PendingEnhancementStatus": {
         "description": "The status of a pending enhancement.\n\n**Allowed values**:\n- `pending`: Enhancement is waiting to be processed.\n- `processing`: Enhancement is currently being processed.\n- `importing`: Enhancement is currently being imported.\n- `indexing`: Enhancement is currently being indexed.\n- `indexing_failed`: Enhancement indexing has failed.\n- `discarded`: Enhancement has been discarded as an exact duplicate.\n- `completed`: Enhancement has been processed successfully.\n- `failed`: Enhancement processing has failed.\n- `expired`: Enhancement lease has expired during processing.",
         "enum": [
            "pending",
            "processing",
            "importing",
            "indexing",
            "indexing_failed",
            "discarded",
            "completed",
            "failed",
            "expired"
         ],
         "title": "PendingEnhancementStatus",
         "type": "string"
      }
   },
   "required": [
      "reference_ids",
      "robot_id"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• enhancement_parameters (dict | None)

• error (str | None)

• id (uuid.UUID)

• pending_enhancements (list[app.domain.references.models.models.PendingEnhancement] | None)

• reference_data_file (app.persistence.blob.models.BlobStorageFile | None)

• reference_ids (list[uuid.UUID])

• request_status (app.domain.references.models.models.EnhancementRequestStatus)

• result_file (app.persistence.blob.models.BlobStorageFile | None)

• robot_id (uuid.UUID)

• source (str | None)

• validation_result_file (app.persistence.blob.models.BlobStorageFile | None)

field enhancement_parameters: dict | None = None

Additional optional parameters to pass through to the robot.

field error: str | None = None

Procedural error affecting all references encountered during the enhancement process. Errors for individual references are provided <TBC>.

field id: UUID [Optional]

The autogenerated database ID.

field pending_enhancements: list[PendingEnhancement] | None = None

List of pending enhancements for the request.

field reference_data_file: BlobStorageFile | None = None

The file containing the reference data for the robot.

field reference_ids: list[UUID] [Required]

The IDs of the references these enhancements are associated with.

field request_status: EnhancementRequestStatus = EnhancementRequestStatus.RECEIVED

The status of the request to create an enhancement.

field result_file: BlobStorageFile | None = None

The file containing the result data from the robot.

field robot_id: UUID [Required]

The robot to request the enhancement from.

field source: str | None = None

The source of the batch enhancement request.

field validation_result_file: BlobStorageFile | None = None

The file containing the validation result data from the robot.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

property n_references: int

The number of references in the request.

class app.domain.references.models.models.EnhancementRequestStatus(*values)

The status of an enhancement request.

ACCEPTED = 'accepted'

Enhancement request has been accepted by the robot.

COMPLETED = 'completed'

All enhancements have been created.

FAILED = 'failed'

All enhancements failed to create.

IMPORTING = 'importing'

Enhancements have been received by the repo and are being imported.

INDEXING = 'indexing'

Enhancements have been imported and are being indexed.

INDEXING_FAILED = 'indexing_failed'

Enhancements have been imported but indexing failed.

PARTIAL_FAILED = 'partial_failed'

Some enhancements failed to create.

PROCESSING = 'processing'

Enhancement request is being processed by the robot.

RECEIVED = 'received'

Enhancement request has been received by the repo.

REJECTED = 'rejected'

Enhancement request has been rejected by the robot.

pydantic model app.domain.references.models.models.Export

A queued job that produces a downloadable file of references.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "Export",
   "description": "A queued job that produces a downloadable file of references.",
   "type": "object",
   "properties": {
      "id": {
         "description": "The autogenerated database ID.",
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "export_format": {
         "$ref": "#/$defs/ExportFormat",
         "default": "jsonl",
         "description": "The serialization format of the produced file."
      },
      "status": {
         "$ref": "#/$defs/ExportStatus",
         "default": "pending",
         "description": "The current status of the export job."
      },
      "result_file": {
         "anyOf": [
            {
               "$ref": "#/$defs/BlobStorageFile"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The file produced by the job, once completed."
      },
      "n_references": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The number of references in the produced file.",
         "title": "N References"
      },
      "error": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Error message, if the job failed.",
         "title": "Error"
      }
   },
   "$defs": {
      "BlobStorageFile": {
         "description": "Model to represent Blob Storage files.",
         "properties": {
            "location": {
               "$ref": "#/$defs/BlobStorageLocation",
               "description": "The location of the blob storage."
            },
            "container": {
               "description": "The name of the container in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in blob storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio",
            "http",
            "https"
         ],
         "title": "BlobStorageLocation",
         "type": "string"
      },
      "ExportFormat": {
         "description": "The serialization format of a reference export.",
         "enum": [
            "jsonl",
            "ris"
         ],
         "title": "ExportFormat",
         "type": "string"
      },
      "ExportStatus": {
         "description": "The status of an export job.",
         "enum": [
            "pending",
            "running",
            "completed",
            "failed"
         ],
         "title": "ExportStatus",
         "type": "string"
      }
   }
}

Config:

• from_attributes: bool = True

Fields:

• error (str | None)

• export_format (app.domain.references.models.models.ExportFormat)

• id (uuid.UUID)

• n_references (int | None)

• result_file (app.persistence.blob.models.BlobStorageFile | None)

• status (app.domain.references.models.models.ExportStatus)

field error: str | None = None

Error message, if the job failed.

field export_format: ExportFormat = ExportFormat.JSONL

The serialization format of the produced file.

field id: UUID [Optional]

The autogenerated database ID.

field n_references: int | None = None

The number of references in the produced file.

field result_file: BlobStorageFile | None = None

The file produced by the job, once completed.

field status: ExportStatus = ExportStatus.PENDING

The current status of the export job.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

class app.domain.references.models.models.ExportFormat(*values)

The serialization format of a reference export.

JSONL = 'jsonl'

JSON Lines: one reference per line.

RIS = 'ris'

RIS: tagged citation format consumed by reference managers.

property extension: str

The file extension for this format.

class app.domain.references.models.models.ExportStatus(*values)

The status of an export job.

COMPLETED = 'completed'

Export job has completed and the file is available.

FAILED = 'failed'

Export job failed before producing a file.

PENDING = 'pending'

Export job has been queued.

RUNNING = 'running'

Export job is being processed.

class app.domain.references.models.models.FacetType(*values)

A facet supported by the reference search facets endpoint.

CONCEPTS = 'concepts'

Counts of references per linked-data concept URI.

COUNTRIES = 'countries'

Counts of references per ISO 3166-1 alpha-2 country code.

COUNTRY_WB_REGIONS = 'country_wb_regions'

Counts of references per World Bank region ID.

pydantic model app.domain.references.models.models.FullTextEnhancement

An enhancement for storing a link to the full text and its metadata.

We separate this from the SDK model as it contains a file pointer, not the URL to the file itself.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "FullTextEnhancement",
   "description": "An enhancement for storing a link to the full text and its metadata.\n\nWe separate this from the SDK model as it contains a file pointer, not\nthe URL to the file itself.",
   "type": "object",
   "properties": {
      "enhancement_type": {
         "const": "full_text",
         "default": "full_text",
         "title": "Enhancement Type",
         "type": "string"
      },
      "blob": {
         "$ref": "#/$defs/BlobStorageFile",
         "description": "Blob storage pointer to the full text file."
      },
      "byte_size": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Size of the file in bytes. If provided on import, will be used to validate the file size. Will always be present on enhancements from the repository.",
         "title": "Byte Size"
      },
      "sha256_checksum": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "SHA256 checksum of the file. If provided on import, will be used to verify the integrity of the file. Will always be present on enhancements from the repository.",
         "title": "Sha256 Checksum"
      },
      "mime_type": {
         "default": "application/pdf",
         "description": "The MIME type of the file.",
         "title": "Mime Type",
         "type": "string"
      },
      "version": {
         "anyOf": [
            {
               "$ref": "#/$defs/DriverVersion"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The version (according to the DRIVER versioning scheme) of this full text."
      },
      "is_oa": {
         "anyOf": [
            {
               "type": "boolean"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "If this full text is Open Access. May be left as null if this is unknown.",
         "title": "Is Oa"
      },
      "license": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The publishing license for this full text.",
         "examples": [
            "apache-2-0",
            "cc-by",
            "cc-by-nc",
            "cc-by-nc-nd",
            "cc-by-nc-sa",
            "cc-by-nd",
            "cc-by-sa",
            "gpl-v2",
            "gpl-v3",
            "isc",
            "mit",
            "other-oa",
            "public-domain"
         ],
         "title": "License"
      },
      "source": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The source from which this full text was obtained.",
         "title": "Source"
      },
      "source_url": {
         "anyOf": [
            {
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The URL of the source from which this full text was obtained.",
         "title": "Source Url"
      },
      "retrieved_at": {
         "anyOf": [
            {
               "format": "date-time",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The timestamp when this full text was retrieved.",
         "title": "Retrieved At"
      }
   },
   "$defs": {
      "BlobStorageFile": {
         "description": "Model to represent Blob Storage files.",
         "properties": {
            "location": {
               "$ref": "#/$defs/BlobStorageLocation",
               "description": "The location of the blob storage."
            },
            "container": {
               "description": "The name of the container in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in blob storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio",
            "http",
            "https"
         ],
         "title": "BlobStorageLocation",
         "type": "string"
      },
      "DriverVersion": {
         "description": "The version based on the DRIVER guidelines versioning scheme.\n\n(Borrowed from OpenAlex)",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "type": "string"
      }
   },
   "required": [
      "blob"
   ]
}

Fields:

• blob (app.persistence.blob.models.BlobStorageFile)

• byte_size (int | None)

• enhancement_type (Literal[destiny_sdk.enhancements.EnhancementType.FULL_TEXT])

• is_oa (bool | None)

• license (str | None)

• mime_type (str)

• retrieved_at (datetime.datetime | None)

• sha256_checksum (str | None)

• source (str | None)

• source_url (pydantic.networks.HttpUrl | None)

• version (destiny_sdk.enhancements.DriverVersion | None)

field blob: BlobStorageFile [Required]

Blob storage pointer to the full text file.

field byte_size: int | None = None

Size of the file in bytes. If provided on import, will be used to validate the file size. Will always be present on enhancements from the repository.

field enhancement_type: Literal[EnhancementType.FULL_TEXT] = EnhancementType.FULL_TEXT

field is_oa: bool | None = None

If this full text is Open Access. May be left as null if this is unknown.

field license: str | None = None

The publishing license for this full text.

field mime_type: str = 'application/pdf'

The MIME type of the file.

field retrieved_at: datetime | None = None

The timestamp when this full text was retrieved.

field sha256_checksum: str | None = None

SHA256 checksum of the file. If provided on import, will be used to verify the integrity of the file. Will always be present on enhancements from the repository.

field source: str | None = None

The source from which this full text was obtained.

field source_url: HttpUrl | None = None

The URL of the source from which this full text was obtained.

field version: DriverVersion | None = None

The version (according to the DRIVER versioning scheme) of this full text.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

property fingerprint: str

The unique fingerprint of this full text enhancement.

Excludes retrieved_at and blob location.

pydantic model app.domain.references.models.models.GenericExternalIdentifier

Generic external identifier model for all subtypes.

The identifier is casted to a string for all inheriters.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "GenericExternalIdentifier",
   "description": "Generic external identifier model for all subtypes.\n\nThe identifier is casted to a string for all inheriters.",
   "type": "object",
   "properties": {
      "identifier": {
         "description": "The identifier itself.",
         "title": "Identifier",
         "type": "string"
      },
      "identifier_type": {
         "anyOf": [
            {
               "$ref": "#/$defs/ExternalIdentifierType"
            },
            {
               "type": "null"
            }
         ],
         "description": "The type of the identifier. If None, identifier is a database id."
      },
      "other_identifier_name": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The name of the other identifier.",
         "title": "Other Identifier Name"
      }
   },
   "$defs": {
      "ExternalIdentifierType": {
         "description": "The type of identifier used to identify a reference.\n\nThis is used to identify the type of identifier used in the `ExternalIdentifier`\nclass.",
         "enum": [
            "doi",
            "eric",
            "pm_id",
            "pro_quest",
            "open_alex",
            "other"
         ],
         "title": "ExternalIdentifierType",
         "type": "string"
      }
   },
   "required": [
      "identifier",
      "identifier_type"
   ]
}

Fields:

• identifier (str)

• identifier_type (destiny_sdk.identifiers.ExternalIdentifierType | None)

• other_identifier_name (str | None)

field identifier: str [Required]

The identifier itself.

field identifier_type: ExternalIdentifierType | None [Required]

The type of the identifier. If None, identifier is a database id.

field other_identifier_name: str | None = None

The name of the other identifier.

classmethod from_specific(external_identifier: Annotated[DOIIdentifier | ERICIdentifier | PubMedIdentifier | ProQuestIdentifier | OpenAlexIdentifier | OtherIdentifier, FieldInfo(annotation=NoneType, required=True, discriminator='identifier_type')]) → Self

Create a generic external identifier from a specific implementation.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

pydantic model app.domain.references.models.models.IdentifierLookup

Model to search for an external identifier.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "IdentifierLookup",
   "description": "Model to search for an external identifier.",
   "type": "object",
   "properties": {
      "identifier": {
         "description": "The identifier itself.",
         "title": "Identifier",
         "type": "string"
      },
      "identifier_type": {
         "anyOf": [
            {
               "$ref": "#/$defs/ExternalIdentifierType"
            },
            {
               "type": "null"
            }
         ],
         "description": "The type of the identifier. If None, identifier is a database id."
      },
      "other_identifier_name": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The name of the other identifier.",
         "title": "Other Identifier Name"
      }
   },
   "$defs": {
      "ExternalIdentifierType": {
         "description": "The type of identifier used to identify a reference.\n\nThis is used to identify the type of identifier used in the `ExternalIdentifier`\nclass.",
         "enum": [
            "doi",
            "eric",
            "pm_id",
            "pro_quest",
            "open_alex",
            "other"
         ],
         "title": "ExternalIdentifierType",
         "type": "string"
      }
   },
   "required": [
      "identifier",
      "identifier_type"
   ]
}

Fields:

• identifier ()

• identifier_type ()

• other_identifier_name ()

field identifier: str [Required]

The identifier itself.

field identifier_type: ExternalIdentifierType | None [Required]

The type of the identifier. If None, identifier is a database id.

field other_identifier_name: str | None = None

The name of the other identifier.

classmethod from_generic(identifier: GenericExternalIdentifier) → Self

Build a lookup from a loosely-typed identifier, validating and canonicalising.

Raises pydantic.ValidationError if the value is not a valid identifier of its declared type.

classmethod from_specific(external_identifier: Annotated[DOIIdentifier | ERICIdentifier | PubMedIdentifier | ProQuestIdentifier | OpenAlexIdentifier | OtherIdentifier, FieldInfo(annotation=NoneType, required=True, discriminator='identifier_type')]) → Self

Create a generic external identifier from a specific implementation.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

pydantic model app.domain.references.models.models.InputSearchability

Whether the input meets the Elasticsearch bibliographic searchability gate.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "InputSearchability",
   "description": "Whether the input meets the Elasticsearch bibliographic searchability gate.",
   "type": "object",
   "properties": {
      "searchable": {
         "description": "Whether the input meets the Elasticsearch searchability gate (title, authors, and publication year unless the selected retrieval policy makes it optional). Exact identifier matching runs regardless, so candidates may be present even when this is false.",
         "title": "Searchable",
         "type": "boolean"
      },
      "reason": {
         "description": "Explanation of the searchability decision.",
         "title": "Reason",
         "type": "string"
      }
   },
   "required": [
      "searchable",
      "reason"
   ]
}

Fields:

• reason (str)

• searchable (bool)

field reason: str [Required]

Explanation of the searchability decision.

field searchable: bool [Required]

Whether the input meets the Elasticsearch searchability gate (title, authors, and publication year unless the selected retrieval policy makes it optional). Exact identifier matching runs regardless, so candidates may be present even when this is false.

pydantic model app.domain.references.models.models.LinkedDataConceptFilter

A set of fully-qualified concept URIs to match on linked_data_concepts.

Within a single filter, references must carry at least one of the listed URIs (logical OR). Multiple filters on a query are ANDed together.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "LinkedDataConceptFilter",
   "description": "A set of fully-qualified concept URIs to match on ``linked_data_concepts``.\n\nWithin a single filter, references must carry at least one of the listed URIs\n(logical OR). Multiple filters on a query are ANDed together.",
   "type": "object",
   "properties": {
      "concept_uris": {
         "description": "Concept URIs to match. At least one must appear on the reference.",
         "items": {
            "type": "string"
         },
         "minItems": 1,
         "title": "Concept Uris",
         "type": "array"
      }
   },
   "required": [
      "concept_uris"
   ]
}

Fields:

• concept_uris (list[str])

field concept_uris: list[str] [Required]

Concept URIs to match. At least one must appear on the reference.

Constraints:

• min_length = 1

pydantic model app.domain.references.models.models.LinkedDataCountryFilter

A set of ISO 3166-1 alpha-2 codes to match on linked_data_countries.

OR within a filter; AND between filters.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "LinkedDataCountryFilter",
   "description": "A set of ISO 3166-1 alpha-2 codes to match on ``linked_data_countries``.\n\nOR within a filter; AND between filters.",
   "type": "object",
   "properties": {
      "country_codes": {
         "description": "ISO 3166-1 alpha-2 country codes. At least one must appear on the reference.",
         "items": {
            "pattern": "^[A-Z]{2}$",
            "type": "string"
         },
         "minItems": 1,
         "title": "Country Codes",
         "type": "array"
      }
   },
   "required": [
      "country_codes"
   ]
}

Fields:

• country_codes (list[str])

field country_codes: list[~typing.Annotated[str, ~pydantic.types.StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Z]{2}$)]] [Required]

ISO 3166-1 alpha-2 country codes. At least one must appear on the reference.

Constraints:

• min_length = 1

pydantic model app.domain.references.models.models.LinkedDataCountryWBRegionFilter

A set of World Bank region IDs to match on linked_data_country_wb_regions.

OR within a filter; AND between filters.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "LinkedDataCountryWBRegionFilter",
   "description": "A set of World Bank region IDs to match on ``linked_data_country_wb_regions``.\n\nOR within a filter; AND between filters.",
   "type": "object",
   "properties": {
      "region_ids": {
         "description": "World Bank region IDs. At least one must appear on the reference.",
         "items": {
            "enum": [
               "EAS",
               "ECS",
               "LCN",
               "MEA",
               "NAC",
               "SAS",
               "SSF"
            ],
            "type": "string"
         },
         "minItems": 1,
         "title": "Region Ids",
         "type": "array"
      }
   },
   "required": [
      "region_ids"
   ]
}

Fields:

• region_ids (list[Literal['EAS', 'ECS', 'LCN', 'MEA', 'NAC', 'SAS', 'SSF']])

field region_ids: list[Literal['EAS', 'ECS', 'LCN', 'MEA', 'NAC', 'SAS', 'SSF']] [Required]

World Bank region IDs. At least one must appear on the reference.

Constraints:

• min_length = 1

pydantic model app.domain.references.models.models.LinkedDataProjection

Result of projecting a LinkedDataEnhancement into flat searchable fields.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "LinkedDataProjection",
   "description": "Result of projecting a LinkedDataEnhancement into flat searchable fields.",
   "type": "object",
   "properties": {
      "concepts": {
         "items": {
            "type": "string"
         },
         "title": "Concepts",
         "type": "array",
         "uniqueItems": true
      },
      "labels": {
         "items": {
            "type": "string"
         },
         "title": "Labels",
         "type": "array",
         "uniqueItems": true
      },
      "evaluated_properties": {
         "items": {
            "type": "string"
         },
         "title": "Evaluated Properties",
         "type": "array",
         "uniqueItems": true
      },
      "countries": {
         "items": {
            "type": "string"
         },
         "title": "Countries",
         "type": "array",
         "uniqueItems": true
      },
      "country_wb_regions": {
         "items": {
            "type": "string"
         },
         "title": "Country Wb Regions",
         "type": "array",
         "uniqueItems": true
      }
   }
}

Fields:

• concepts (set[str])

• countries (set[str])

• country_wb_regions (set[str])

• evaluated_properties (set[str])

• labels (set[str])

field concepts: set[str] [Optional]

field countries: set[str] [Optional]

field country_wb_regions: set[str] [Optional]

field evaluated_properties: set[str] [Optional]

field labels: set[str] [Optional]

pydantic model app.domain.references.models.models.LinkedExternalIdentifier

External identifier model with database attributes included.

Show Entity Relationship Diagram

Show JSON schema

{
   "$defs": {
      "AbstractContentEnhancement": {
         "description": "An enhancement which is specific to the abstract of a reference.\n\nThis is separate from the `BibliographicMetadata` for two reasons:\n\n1. Abstracts are increasingly missing from sources like OpenAlex, and may be\nbackfilled from other sources, without the bibliographic metadata.\n2. They are also subject to copyright limitations in ways which metadata are\nnot, and thus need separate visibility controls.",
         "properties": {
            "enhancement_type": {
               "const": "abstract",
               "default": "abstract",
               "title": "Enhancement Type",
               "type": "string"
            },
            "process": {
               "$ref": "#/$defs/AbstractProcessType"
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquire the abstract.",
         "enum": [
            "uninverted",
            "closed_api",
            "other"
         ],
         "title": "AbstractProcessType",
         "type": "string"
      },
      "AnnotationEnhancement": {
         "description": "An enhancement which is composed of a list of Annotations.",
         "properties": {
            "enhancement_type": {
               "const": "annotation",
               "default": "annotation",
               "title": "Enhancement Type",
               "type": "string"
            },
            "annotations": {
               "items": {
                  "discriminator": {
                     "mapping": {
                        "boolean": "#/$defs/BooleanAnnotation",
                        "score": "#/$defs/ScoreAnnotation"
                     },
                     "propertyName": "annotation_type"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/BooleanAnnotation"
                     },
                     {
                        "$ref": "#/$defs/ScoreAnnotation"
                     }
                  ]
               },
               "minItems": 1,
               "title": "Annotations",
               "type": "array"
            }
         },
         "required": [
            "annotations"
         ],
         "title": "AnnotationEnhancement",
         "type": "object"
      },
      "AuthorPosition": {
         "description": "The position of an author in a list of authorships.\n\nMaps to the data from OpenAlex.",
         "enum": [
            "first",
            "middle",
            "last"
         ],
         "title": "AuthorPosition",
         "type": "string"
      },
      "Authorship": {
         "description": "Represents a single author and their association with a reference.\n\nThis is a simplification of the OpenAlex [Authorship\nobject](https://docs.openalex.org/api-entities/works/work-object/authorship-object)\nfor our purposes.",
         "properties": {
            "display_name": {
               "description": "The display name of the author. Expected format FIRSTNAME <MIDDLENAME> LASTNAME. Providing display_name in an unexpected format will affect search performance.",
               "title": "Display Name",
               "type": "string"
            },
            "orcid": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ORCid of the author.",
               "title": "Orcid"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "position"
         ],
         "title": "Authorship",
         "type": "object"
      },
      "BibliographicMetadataEnhancement": {
         "description": "An enhancement which is made up of bibliographic metadata.\n\nGenerally this will be sourced from a database such as OpenAlex or similar.\nFor directly contributed references, these may not be complete.",
         "properties": {
            "enhancement_type": {
               "const": "bibliographic",
               "default": "bibliographic",
               "title": "Enhancement Type",
               "type": "string"
            },
            "authorship": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Authorship"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `Authorships` belonging to this reference.",
               "title": "Authorship"
            },
            "cited_by_count": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex) The number of citations to this work. These are the times that\nother works have cited this work\n",
               "title": "Cited By Count"
            },
            "created_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date this metadata record was created",
               "title": "Created Date"
            },
            "updated_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date of the last OpenAlex update to this metadata",
               "title": "Updated Date"
            },
            "publication_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The date which the version of record was published.",
               "title": "Publication Date"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The year in which the version of record was published.",
               "title": "Publication Year"
            },
            "publisher": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the entity which published the version of record.",
               "title": "Publisher"
            },
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The title of the reference.",
               "title": "Title"
            },
            "pagination": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Pagination"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Pagination info (volume, issue, pages)."
            },
            "publication_venue": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenue"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Publication venue information (journal, repository, etc.)."
            }
         },
         "title": "BibliographicMetadataEnhancement",
         "type": "object"
      },
      "BlobStorageFile": {
         "description": "Model to represent Blob Storage files.",
         "properties": {
            "location": {
               "$ref": "#/$defs/BlobStorageLocation",
               "description": "The location of the blob storage."
            },
            "container": {
               "description": "The name of the container in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in blob storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio",
            "http",
            "https"
         ],
         "title": "BlobStorageLocation",
         "type": "string"
      },
      "BooleanAnnotation": {
         "description": "An annotation is a way of tagging the content with a label of some kind.\n\nThis class will probably be broken up in the future, but covers most of our\ninitial cases.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "value": {
               "description": "Boolean flag for this annotation",
               "title": "Value",
               "type": "boolean"
            },
            "score": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A confidence score for this annotation",
               "title": "Score"
            },
            "data": {
               "additionalProperties": true,
               "description": "\nAn object representation of the annotation including any confidence scores or\ndescriptions.\n",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "value"
         ],
         "title": "BooleanAnnotation",
         "type": "object"
      },
      "DOIIdentifier": {
         "description": "An external identifier representing a DOI.",
         "properties": {
            "identifier": {
               "description": "The DOI of the reference. Format: '10.<registrant>/<suffix>' where registrant is 4-9 digits and suffix is any non-whitespace characters. Examples: 10.1000/journal.pone.0001, 10.18730/9WQ$D, 10.1000/\u00e9dition",
               "pattern": "^10\\.\\d{4,9}/\\S+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "doi",
               "default": "doi",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "DOIIdentifier",
         "type": "object"
      },
      "DriverVersion": {
         "description": "The version based on the DRIVER guidelines versioning scheme.\n\n(Borrowed from OpenAlex)",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "type": "string"
      },
      "DuplicateDetermination": {
         "description": "The determination of whether a reference is a duplicate.\n\nThis encodes both a status and a determination.",
         "enum": [
            "pending",
            "nominated",
            "duplicate",
            "exact_duplicate",
            "canonical",
            "unresolved",
            "unsearchable",
            "decoupled"
         ],
         "title": "DuplicateDetermination",
         "type": "string"
      },
      "ERICIdentifier": {
         "description": "An external identifier representing an ERIC Number.\n\nAn ERIC Number is defined as a unique identifying number preceded by\nED (for a non-journal document) or EJ (for a journal article).",
         "properties": {
            "identifier": {
               "description": "The ERIC Number. Format: 'ED' or 'EJ' followed by digits. Example: ED123456 or EJ789012",
               "pattern": "E[D|J][0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "eric",
               "default": "eric",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ERICIdentifier",
         "type": "object"
      },
      "Enhancement": {
         "description": "Core enhancement model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "created_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp at which the object was created.",
               "title": "Created At"
            },
            "updated_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp at which the object was last updated.",
               "title": "Updated At"
            },
            "source": {
               "description": "The enhancement source for tracking provenance.",
               "title": "Source",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "description": "The level of visibility of the enhancement"
            },
            "robot_version": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version of the robot that generated the content.",
               "title": "Robot Version"
            },
            "derived_from": {
               "anyOf": [
                  {
                     "items": {
                        "format": "uuid",
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of enhancement IDs that this enhancement was derived from.",
               "title": "Derived From"
            },
            "content": {
               "description": "The content of the enhancement.",
               "discriminator": {
                  "mapping": {
                     "abstract": "#/$defs/AbstractContentEnhancement",
                     "annotation": "#/$defs/AnnotationEnhancement",
                     "bibliographic": "#/$defs/BibliographicMetadataEnhancement",
                     "full_text": "#/$defs/FullTextEnhancement",
                     "linked_data": "#/$defs/LinkedDataEnhancement",
                     "location": "#/$defs/LocationEnhancement",
                     "raw": "#/$defs/RawEnhancement",
                     "reference_association": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LinkedDataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/FullTextEnhancement"
                  },
                  {
                     "$ref": "#/$defs/RawEnhancement"
                  }
               ],
               "title": "Content"
            },
            "reference_id": {
               "description": "The ID of the reference this enhancement is associated with.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The reference this enhancement is associated with."
            }
         },
         "required": [
            "source",
            "visibility",
            "content",
            "reference_id"
         ],
         "title": "Enhancement",
         "type": "object"
      },
      "FullTextEnhancement": {
         "description": "An enhancement for storing a link to the full text and its metadata.\n\nWe separate this from the SDK model as it contains a file pointer, not\nthe URL to the file itself.",
         "properties": {
            "enhancement_type": {
               "const": "full_text",
               "default": "full_text",
               "title": "Enhancement Type",
               "type": "string"
            },
            "blob": {
               "$ref": "#/$defs/BlobStorageFile",
               "description": "Blob storage pointer to the full text file."
            },
            "byte_size": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Size of the file in bytes. If provided on import, will be used to validate the file size. Will always be present on enhancements from the repository.",
               "title": "Byte Size"
            },
            "sha256_checksum": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "SHA256 checksum of the file. If provided on import, will be used to verify the integrity of the file. Will always be present on enhancements from the repository.",
               "title": "Sha256 Checksum"
            },
            "mime_type": {
               "default": "application/pdf",
               "description": "The MIME type of the file.",
               "title": "Mime Type",
               "type": "string"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version (according to the DRIVER versioning scheme) of this full text."
            },
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "If this full text is Open Access. May be left as null if this is unknown.",
               "title": "Is Oa"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The publishing license for this full text.",
               "examples": [
                  "apache-2-0",
                  "cc-by",
                  "cc-by-nc",
                  "cc-by-nc-nd",
                  "cc-by-nc-sa",
                  "cc-by-nd",
                  "cc-by-sa",
                  "gpl-v2",
                  "gpl-v3",
                  "isc",
                  "mit",
                  "other-oa",
                  "public-domain"
               ],
               "title": "License"
            },
            "source": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The source from which this full text was obtained.",
               "title": "Source"
            },
            "source_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The URL of the source from which this full text was obtained.",
               "title": "Source Url"
            },
            "retrieved_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp when this full text was retrieved.",
               "title": "Retrieved At"
            }
         },
         "required": [
            "blob"
         ],
         "title": "FullTextEnhancement",
         "type": "object"
      },
      "JsonValue": {},
      "LinkedDataEnhancement": {
         "description": "An enhancement for storing structured data in a linked data format.\n\nThe content is a JSON-LD document conforming to the vocabulary and\ncontext specified. This enhancement type is produced by mapping robots\nthat transform RawEnhancement data into the shared vocabulary.",
         "properties": {
            "enhancement_type": {
               "const": "linked_data",
               "default": "linked_data",
               "title": "Enhancement Type",
               "type": "string"
            },
            "vocabulary_uri": {
               "description": "The URI of the vocabulary against which this data was produced. Used for compatibility checking.",
               "examples": [
                  "https://vocab.evrepo.org/vocabulary/v1"
               ],
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "Vocabulary Uri",
               "type": "string"
            },
            "data": {
               "additionalProperties": {
                  "$ref": "#/$defs/JsonValue"
               },
               "description": "The JSON-LD content. Must contain an '@context' key with a valid URI string. When combined with the @context, this forms a complete linked data graph.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "vocabulary_uri",
            "data"
         ],
         "title": "LinkedDataEnhancement",
         "type": "object"
      },
      "LinkedExternalIdentifier": {
         "description": "External identifier model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "identifier": {
               "description": "The identifier itself.",
               "discriminator": {
                  "mapping": {
                     "doi": "#/$defs/DOIIdentifier",
                     "eric": "#/$defs/ERICIdentifier",
                     "open_alex": "#/$defs/OpenAlexIdentifier",
                     "other": "#/$defs/OtherIdentifier",
                     "pm_id": "#/$defs/PubMedIdentifier",
                     "pro_quest": "#/$defs/ProQuestIdentifier"
                  },
                  "propertyName": "identifier_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/DOIIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ERICIdentifier"
                  },
                  {
                     "$ref": "#/$defs/PubMedIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ProQuestIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OpenAlexIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OtherIdentifier"
                  }
               ],
               "title": "Identifier"
            },
            "reference_id": {
               "description": "The ID of the reference this identifier identifies.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The reference this identifier identifies."
            }
         },
         "required": [
            "identifier",
            "reference_id"
         ],
         "title": "LinkedExternalIdentifier",
         "type": "object"
      },
      "Location": {
         "description": "A location where a reference can be found.\n\nThis maps almost completely to the OpenAlex\n[Location object](https://docs.openalex.org/api-entities/works/work-object/location-object)",
         "properties": {
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): True if an Open Access (OA) version of this work is available\nat this location. May be left as null if this is unknown (and thus)\ntreated effectively as `false`.\n",
               "title": "Is Oa"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\nThe version (according to the DRIVER versioning scheme) of this location.\n"
            },
            "landing_page_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "(From OpenAlex): The landing page URL for this location.",
               "title": "Landing Page Url"
            },
            "pdf_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): A URL where you can find this location as a PDF.\n",
               "title": "Pdf Url"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): The location's publishing license. This can be a Creative\nCommons license such as cc0 or cc-by, a publisher-specific license, or null\nwhich means we are not able to determine a license for this location.\n",
               "title": "License"
            },
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Any extra metadata about this location",
               "title": "Extra"
            }
         },
         "title": "Location",
         "type": "object"
      },
      "LocationEnhancement": {
         "description": "An enhancement which describes locations where this reference can be found.\n\nThis maps closely (almost exactly) to OpenAlex's locations.",
         "properties": {
            "enhancement_type": {
               "const": "location",
               "default": "location",
               "title": "Enhancement Type",
               "type": "string"
            },
            "locations": {
               "description": "A list of locations where this reference can be found.",
               "items": {
                  "$ref": "#/$defs/Location"
               },
               "minItems": 1,
               "title": "Locations",
               "type": "array"
            }
         },
         "required": [
            "locations"
         ],
         "title": "LocationEnhancement",
         "type": "object"
      },
      "OpenAlexIdentifier": {
         "description": "An external identifier representing an OpenAlex ID.",
         "properties": {
            "identifier": {
               "description": "The OpenAlex ID of the reference. Format: 'W' followed by digits. Example: W2741809807",
               "pattern": "^W\\d+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "open_alex",
               "default": "open_alex",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "OpenAlexIdentifier",
         "type": "object"
      },
      "OtherIdentifier": {
         "description": "An external identifier not otherwise defined by the repository.",
         "properties": {
            "identifier": {
               "description": "The identifier of the reference.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "other",
               "default": "other",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            },
            "other_identifier_name": {
               "description": "The name of the undocumented identifier type.",
               "title": "Other Identifier Name",
               "type": "string"
            }
         },
         "required": [
            "identifier",
            "other_identifier_name"
         ],
         "title": "OtherIdentifier",
         "type": "object"
      },
      "Pagination": {
         "description": "Pagination information for journal articles.\n\nMaps to OpenAlex's work.biblio object. All fields are strings to match\nOpenAlex's format, which may include non-numeric values like \"Spring\" or \"A1\".",
         "properties": {
            "volume": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The volume number of the journal/publication.",
               "title": "Volume"
            },
            "issue": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The issue number of the journal/publication.",
               "title": "Issue"
            },
            "first_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The first page number of the reference in the publication.",
               "title": "First Page"
            },
            "last_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The last page number of the reference in the publication.",
               "title": "Last Page"
            }
         },
         "title": "Pagination",
         "type": "object"
      },
      "ProQuestIdentifier": {
         "description": "An external identifier representing a ProQuest ID.",
         "properties": {
            "identifier": {
               "description": "The ProQuest ID of the reference. Format: numeric digits only. Example: 12345678",
               "pattern": "[0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "pro_quest",
               "default": "pro_quest",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ProQuestIdentifier",
         "type": "object"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID (PMID) of the reference. Example: 12345678",
               "exclusiveMinimum": 0,
               "title": "Identifier",
               "type": "integer"
            },
            "identifier_type": {
               "const": "pm_id",
               "default": "pm_id",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "PubMedIdentifier",
         "type": "object"
      },
      "PublicationVenue": {
         "description": "A publication venue (journal, repository, conference, etc.).",
         "properties": {
            "display_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The display name of the venue (journal name, repository name, etc.)",
               "title": "Display Name"
            },
            "venue_type": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenueType"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The type of venue: journal, repository, book, conference, etc."
            },
            "issn": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of ISSNs associated with this venue (print and electronic)",
               "title": "Issn"
            },
            "issn_l": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The linking ISSN - a canonical ISSN for the venue across format changes",
               "title": "Issn L"
            },
            "host_organization_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Display name of the host organization (publisher)",
               "title": "Host Organization Name"
            }
         },
         "title": "PublicationVenue",
         "type": "object"
      },
      "PublicationVenueType": {
         "description": "Type of publication venue.\n\nAligns with OpenAlex source types.",
         "enum": [
            "journal",
            "repository",
            "conference",
            "ebook_platform",
            "book_series",
            "other"
         ],
         "title": "PublicationVenueType",
         "type": "string"
      },
      "RawEnhancement": {
         "description": "An enhancement for storing raw/arbitrary/unstructured data.\n\nData in these enhancements is intended for future conversion into structured form.\n\nThis enhancement accepts any fields passed in to `data`. These enhancements cannot\nbe created by robots.",
         "properties": {
            "enhancement_type": {
               "const": "raw",
               "default": "raw",
               "title": "Enhancement Type",
               "type": "string"
            },
            "source_export_date": {
               "description": "Date the enhancement data was retrieved.",
               "format": "date-time",
               "title": "Source Export Date",
               "type": "string"
            },
            "description": {
               "description": "Description of the data to aid in future refinement.",
               "title": "Description",
               "type": "string"
            },
            "metadata": {
               "additionalProperties": true,
               "description": "Additional metadata to aid in future structuring of raw data",
               "title": "Metadata",
               "type": "object"
            },
            "data": {
               "description": "Unstructured data for later processing.",
               "title": "Data"
            }
         },
         "required": [
            "source_export_date",
            "description",
            "data"
         ],
         "title": "RawEnhancement",
         "type": "object"
      },
      "Reference": {
         "description": "Core reference model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "default": "public",
               "description": "The level of visibility of the reference"
            },
            "identifiers": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/LinkedExternalIdentifier"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `LinkedExternalIdentifiers` for the Reference",
               "title": "Identifiers"
            },
            "enhancements": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Enhancement"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of enhancements for the reference",
               "title": "Enhancements"
            },
            "duplicate_decision": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/ReferenceDuplicateDecision"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The current active duplicate decision for this reference. If None, either duplicate_decision has not been preloaded or the duplicate status is pending."
            },
            "canonical_reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The canonical reference that this reference is a duplicate of"
            },
            "duplicate_references": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Reference"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of references that this reference duplicates",
               "title": "Duplicate References"
            }
         },
         "title": "Reference",
         "type": "object"
      },
      "ReferenceAssociationEnhancement": {
         "description": "An enhancement for storing associations between references.",
         "properties": {
            "enhancement_type": {
               "const": "reference_association",
               "default": "reference_association",
               "title": "Enhancement Type",
               "type": "string"
            },
            "associated_reference_ids": {
               "description": "A list of Identifiers which are associated to this reference. These can either be ExternalIdentifiers or resolved repository UUID4s.",
               "items": {
                  "anyOf": [
                     {
                        "discriminator": {
                           "mapping": {
                              "doi": "#/$defs/DOIIdentifier",
                              "eric": "#/$defs/ERICIdentifier",
                              "open_alex": "#/$defs/OpenAlexIdentifier",
                              "other": "#/$defs/OtherIdentifier",
                              "pm_id": "#/$defs/PubMedIdentifier",
                              "pro_quest": "#/$defs/ProQuestIdentifier"
                           },
                           "propertyName": "identifier_type"
                        },
                        "oneOf": [
                           {
                              "$ref": "#/$defs/DOIIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ERICIdentifier"
                           },
                           {
                              "$ref": "#/$defs/PubMedIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ProQuestIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OpenAlexIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OtherIdentifier"
                           }
                        ]
                     },
                     {
                        "anyOf": [
                           {
                              "format": "uuid4",
                              "type": "string"
                           },
                           {
                              "format": "uuid7",
                              "type": "string"
                           }
                        ],
                        "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
                     }
                  ]
               },
               "minItems": 1,
               "title": "Associated Reference Ids",
               "type": "array"
            },
            "association_type": {
               "$ref": "#/$defs/ReferenceAssociationType",
               "description": "The type of association between this reference and the associated ones. Direction is important: \"this reference <association_type> associated reference\"."
            }
         },
         "required": [
            "associated_reference_ids",
            "association_type"
         ],
         "title": "ReferenceAssociationEnhancement",
         "type": "object"
      },
      "ReferenceAssociationType": {
         "description": "The type of association between references.\n\nDirection is important: \"this reference <association_type> associated reference\".",
         "enum": [
            "cites",
            "is_cited_by",
            "is_similar_to"
         ],
         "title": "ReferenceAssociationType",
         "type": "string"
      },
      "ReferenceDuplicateDecision": {
         "description": "Model representing a decision on whether a reference is a duplicate.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "reference_id": {
               "description": "The ID of the reference being evaluated.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "enhancement_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the enhancement that triggered this duplicate decision, if any.",
               "title": "Enhancement Id"
            },
            "active_decision": {
               "default": false,
               "description": "Whether this is the active decision for the reference.",
               "title": "Active Decision",
               "type": "boolean"
            },
            "candidate_canonical_ids": {
               "description": "A list of candidate canonical IDs for the reference.",
               "items": {
                  "format": "uuid",
                  "type": "string"
               },
               "title": "Candidate Canonical Ids",
               "type": "array"
            },
            "duplicate_determination": {
               "$ref": "#/$defs/DuplicateDetermination",
               "default": "pending",
               "description": "The duplicate status of the reference."
            },
            "canonical_reference_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the canonical reference this reference duplicates.",
               "title": "Canonical Reference Id"
            },
            "detail": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Optional additional detail about the decision.",
               "title": "Detail"
            }
         },
         "required": [
            "reference_id"
         ],
         "title": "ReferenceDuplicateDecision",
         "type": "object"
      },
      "ScoreAnnotation": {
         "description": "An annotation which represents the score for a label.\n\nThis is similar to a BooleanAnnotation, but lacks a boolean determination\nas to the application of the label.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "score": {
               "description": "Score for this annotation",
               "title": "Score",
               "type": "number"
            },
            "data": {
               "additionalProperties": true,
               "description": "An object representation of the annotation including any confidence scores or descriptions.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "score"
         ],
         "title": "ScoreAnnotation",
         "type": "object"
      },
      "Visibility": {
         "description": "The visibility of a data element in the repository.\n\nThis is used to manage whether information should be publicly available or\nrestricted (generally due to copyright constraints from publishers).\n\nTODO: Implement data governance layer to manage this.",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   },
   "$ref": "#/$defs/LinkedExternalIdentifier"
}

Config:

• from_attributes: bool = True

Fields:

• id (uuid.UUID)

• identifier (destiny_sdk.identifiers.DOIIdentifier | destiny_sdk.identifiers.ERICIdentifier | destiny_sdk.identifiers.PubMedIdentifier | destiny_sdk.identifiers.ProQuestIdentifier | destiny_sdk.identifiers.OpenAlexIdentifier | destiny_sdk.identifiers.OtherIdentifier)

• reference (app.domain.references.models.models.Reference | None)

• reference_id (uuid.UUID)

field id: UUID [Optional]

The autogenerated database ID.

field identifier: Annotated[DOIIdentifier | ERICIdentifier | PubMedIdentifier | ProQuestIdentifier | OpenAlexIdentifier | OtherIdentifier, FieldInfo(annotation=NoneType, required=True, discriminator='identifier_type')] [Required]

The identifier itself.

field reference: Reference | None = None

The reference this identifier identifies.

field reference_id: UUID [Required]

The ID of the reference this identifier identifies.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

hash_data() → int

Contentwise hash of the identifier, excluding relationships.

pydantic model app.domain.references.models.models.PendingEnhancement

A pending enhancement.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "PendingEnhancement",
   "description": "A pending enhancement.",
   "type": "object",
   "properties": {
      "id": {
         "description": "The autogenerated database ID.",
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "reference_id": {
         "description": "The ID of the reference to be enhanced.",
         "format": "uuid",
         "title": "Reference Id",
         "type": "string"
      },
      "robot_id": {
         "description": "The ID of the robot that will perform the enhancement.",
         "format": "uuid",
         "title": "Robot Id",
         "type": "string"
      },
      "enhancement_request_id": {
         "anyOf": [
            {
               "format": "uuid",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The ID of the batch enhancement request that this pending enhancement belongs to.",
         "title": "Enhancement Request Id"
      },
      "robot_enhancement_batch_id": {
         "anyOf": [
            {
               "format": "uuid",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The ID of the robot enhancement batch that this pending enhancement belongs to.",
         "title": "Robot Enhancement Batch Id"
      },
      "status": {
         "$ref": "#/$defs/PendingEnhancementStatus",
         "default": "pending",
         "description": "The status of the pending enhancement."
      },
      "source": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The source of the pending enhancement for provenance tracking, if not an enhancement request.",
         "title": "Source"
      },
      "expires_at": {
         "default": "1970-01-01T00:00:00Z",
         "description": "The datetime at which the pending enhancement expires.",
         "format": "date-time",
         "title": "Expires At",
         "type": "string"
      },
      "retry_of": {
         "anyOf": [
            {
               "format": "uuid",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The ID of the pending enhancement that this is a retry of, if any.",
         "title": "Retry Of"
      }
   },
   "$defs": {
      "PendingEnhancementStatus": {
         "description": "The status of a pending enhancement.\n\n**Allowed values**:\n- `pending`: Enhancement is waiting to be processed.\n- `processing`: Enhancement is currently being processed.\n- `importing`: Enhancement is currently being imported.\n- `indexing`: Enhancement is currently being indexed.\n- `indexing_failed`: Enhancement indexing has failed.\n- `discarded`: Enhancement has been discarded as an exact duplicate.\n- `completed`: Enhancement has been processed successfully.\n- `failed`: Enhancement processing has failed.\n- `expired`: Enhancement lease has expired during processing.",
         "enum": [
            "pending",
            "processing",
            "importing",
            "indexing",
            "indexing_failed",
            "discarded",
            "completed",
            "failed",
            "expired"
         ],
         "title": "PendingEnhancementStatus",
         "type": "string"
      }
   },
   "required": [
      "reference_id",
      "robot_id"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• enhancement_request_id (uuid.UUID | None)

• expires_at (datetime.datetime)

• id (uuid.UUID)

• reference_id (uuid.UUID)

• retry_of (uuid.UUID | None)

• robot_enhancement_batch_id (uuid.UUID | None)

• robot_id (uuid.UUID)

• source (str | None)

• status (app.domain.references.models.models.PendingEnhancementStatus)

Validators:

• check_enhancement_request_or_source_present » all fields

• set_expires_at » expires_at

field enhancement_request_id: UUID | None = None

The ID of the batch enhancement request that this pending enhancement belongs to.

Validated by:

• check_enhancement_request_or_source_present

field expires_at: datetime = datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc)

The datetime at which the pending enhancement expires.

Validated by:

• check_enhancement_request_or_source_present

• set_expires_at

field id: UUID [Optional]

The autogenerated database ID.

Validated by:

• check_enhancement_request_or_source_present

field reference_id: UUID [Required]

The ID of the reference to be enhanced.

Validated by:

• check_enhancement_request_or_source_present

field retry_of: UUID | None = None

The ID of the pending enhancement that this is a retry of, if any.

Validated by:

• check_enhancement_request_or_source_present

field robot_enhancement_batch_id: UUID | None = None

The ID of the robot enhancement batch that this pending enhancement belongs to.

Validated by:

• check_enhancement_request_or_source_present

field robot_id: UUID [Required]

The ID of the robot that will perform the enhancement.

Validated by:

• check_enhancement_request_or_source_present

field source: str | None = None

The source of the pending enhancement for provenance tracking, if not an enhancement request.

Validated by:

• check_enhancement_request_or_source_present

field status: PendingEnhancementStatus = PendingEnhancementStatus.PENDING

The status of the pending enhancement.

Validated by:

• check_enhancement_request_or_source_present

validator set_expires_at  »  expires_at

Allow setting expires_at as a timedelta from now on instantiation.

validator check_enhancement_request_or_source_present  »  all fields

Ensure either enhancement request ID or source is present.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

class app.domain.references.models.models.PendingEnhancementStatus(*values)

The status of a pending enhancement.

Allowed values: - pending: Enhancement is waiting to be processed. - processing: Enhancement is currently being processed. - importing: Enhancement is currently being imported. - indexing: Enhancement is currently being indexed. - indexing_failed: Enhancement indexing has failed. - discarded: Enhancement has been discarded as an exact duplicate. - completed: Enhancement has been processed successfully. - failed: Enhancement processing has failed. - expired: Enhancement lease has expired during processing.

COMPLETED = 'completed'

DISCARDED = 'discarded'

EXPIRED = 'expired'

FAILED = 'failed'

IMPORTING = 'importing'

INDEXING = 'indexing'

INDEXING_FAILED = 'indexing_failed'

PENDING = 'pending'

PROCESSING = 'processing'

can_transition_to(new_status: StateMachineType) → bool

Check if transition from current status to new status is allowed.

Args:

new_status: The target status to transition to

Returns:

True if transition is allowed, False otherwise

guard_transition(new_status: StateMachineType, entity_id: object) → None

Guard against invalid state transitions.

Raises StateTransitionError if transition is not allowed.

Args:

new_status: The target status to transition to entity_id: The ID of the entity attempting the transition

Raises:

StateTransitionError: If the transition is not allowed

classmethod transitions() → dict[PendingEnhancementStatus, set[PendingEnhancementStatus]]

Define the allowed state transitions for pending enhancements.

Returns a mapping of current status to set of allowed next statuses. Empty set means the status is terminal (no transitions allowed).

        stateDiagram-v2
    PENDING --> PROCESSING
    PROCESSING --> IMPORTING
    PROCESSING --> EXPIRED
    PROCESSING --> FAILED
    IMPORTING --> INDEXING
    IMPORTING --> DISCARDED
    IMPORTING --> FAILED
    INDEXING --> COMPLETED
    INDEXING --> INDEXING_FAILED
    

pydantic model app.domain.references.models.models.PublicationYearRange

A range of publication years for filtering search results.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "PublicationYearRange",
   "description": "A range of publication years for filtering search results.",
   "type": "object",
   "properties": {
      "start": {
         "anyOf": [
            {
               "exclusiveMinimum": 0,
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Start year (inclusive)",
         "title": "Start"
      },
      "end": {
         "anyOf": [
            {
               "exclusiveMinimum": 0,
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "End year (inclusive)",
         "title": "End"
      }
   }
}

Fields:

• end (int | None)

• start (int | None)

Validators:

• validate_end_ge_start » all fields

field end: Annotated[int, Gt(gt=0)] | None = None

End year (inclusive)

Validated by:

• validate_end_ge_start

field start: Annotated[int, Gt(gt=0)] | None = None

Start year (inclusive)

Validated by:

• validate_end_ge_start

validator validate_end_ge_start  »  all fields

Validate that end year is greater than or equal to start year.

pydantic model app.domain.references.models.models.Reference

Core reference model with database attributes included.

Show Entity Relationship Diagram

Show JSON schema

{
   "$defs": {
      "AbstractContentEnhancement": {
         "description": "An enhancement which is specific to the abstract of a reference.\n\nThis is separate from the `BibliographicMetadata` for two reasons:\n\n1. Abstracts are increasingly missing from sources like OpenAlex, and may be\nbackfilled from other sources, without the bibliographic metadata.\n2. They are also subject to copyright limitations in ways which metadata are\nnot, and thus need separate visibility controls.",
         "properties": {
            "enhancement_type": {
               "const": "abstract",
               "default": "abstract",
               "title": "Enhancement Type",
               "type": "string"
            },
            "process": {
               "$ref": "#/$defs/AbstractProcessType"
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquire the abstract.",
         "enum": [
            "uninverted",
            "closed_api",
            "other"
         ],
         "title": "AbstractProcessType",
         "type": "string"
      },
      "AnnotationEnhancement": {
         "description": "An enhancement which is composed of a list of Annotations.",
         "properties": {
            "enhancement_type": {
               "const": "annotation",
               "default": "annotation",
               "title": "Enhancement Type",
               "type": "string"
            },
            "annotations": {
               "items": {
                  "discriminator": {
                     "mapping": {
                        "boolean": "#/$defs/BooleanAnnotation",
                        "score": "#/$defs/ScoreAnnotation"
                     },
                     "propertyName": "annotation_type"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/BooleanAnnotation"
                     },
                     {
                        "$ref": "#/$defs/ScoreAnnotation"
                     }
                  ]
               },
               "minItems": 1,
               "title": "Annotations",
               "type": "array"
            }
         },
         "required": [
            "annotations"
         ],
         "title": "AnnotationEnhancement",
         "type": "object"
      },
      "AuthorPosition": {
         "description": "The position of an author in a list of authorships.\n\nMaps to the data from OpenAlex.",
         "enum": [
            "first",
            "middle",
            "last"
         ],
         "title": "AuthorPosition",
         "type": "string"
      },
      "Authorship": {
         "description": "Represents a single author and their association with a reference.\n\nThis is a simplification of the OpenAlex [Authorship\nobject](https://docs.openalex.org/api-entities/works/work-object/authorship-object)\nfor our purposes.",
         "properties": {
            "display_name": {
               "description": "The display name of the author. Expected format FIRSTNAME <MIDDLENAME> LASTNAME. Providing display_name in an unexpected format will affect search performance.",
               "title": "Display Name",
               "type": "string"
            },
            "orcid": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ORCid of the author.",
               "title": "Orcid"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "position"
         ],
         "title": "Authorship",
         "type": "object"
      },
      "BibliographicMetadataEnhancement": {
         "description": "An enhancement which is made up of bibliographic metadata.\n\nGenerally this will be sourced from a database such as OpenAlex or similar.\nFor directly contributed references, these may not be complete.",
         "properties": {
            "enhancement_type": {
               "const": "bibliographic",
               "default": "bibliographic",
               "title": "Enhancement Type",
               "type": "string"
            },
            "authorship": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Authorship"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `Authorships` belonging to this reference.",
               "title": "Authorship"
            },
            "cited_by_count": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex) The number of citations to this work. These are the times that\nother works have cited this work\n",
               "title": "Cited By Count"
            },
            "created_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date this metadata record was created",
               "title": "Created Date"
            },
            "updated_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date of the last OpenAlex update to this metadata",
               "title": "Updated Date"
            },
            "publication_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The date which the version of record was published.",
               "title": "Publication Date"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The year in which the version of record was published.",
               "title": "Publication Year"
            },
            "publisher": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the entity which published the version of record.",
               "title": "Publisher"
            },
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The title of the reference.",
               "title": "Title"
            },
            "pagination": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Pagination"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Pagination info (volume, issue, pages)."
            },
            "publication_venue": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenue"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Publication venue information (journal, repository, etc.)."
            }
         },
         "title": "BibliographicMetadataEnhancement",
         "type": "object"
      },
      "BlobStorageFile": {
         "description": "Model to represent Blob Storage files.",
         "properties": {
            "location": {
               "$ref": "#/$defs/BlobStorageLocation",
               "description": "The location of the blob storage."
            },
            "container": {
               "description": "The name of the container in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in blob storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio",
            "http",
            "https"
         ],
         "title": "BlobStorageLocation",
         "type": "string"
      },
      "BooleanAnnotation": {
         "description": "An annotation is a way of tagging the content with a label of some kind.\n\nThis class will probably be broken up in the future, but covers most of our\ninitial cases.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "value": {
               "description": "Boolean flag for this annotation",
               "title": "Value",
               "type": "boolean"
            },
            "score": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A confidence score for this annotation",
               "title": "Score"
            },
            "data": {
               "additionalProperties": true,
               "description": "\nAn object representation of the annotation including any confidence scores or\ndescriptions.\n",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "value"
         ],
         "title": "BooleanAnnotation",
         "type": "object"
      },
      "DOIIdentifier": {
         "description": "An external identifier representing a DOI.",
         "properties": {
            "identifier": {
               "description": "The DOI of the reference. Format: '10.<registrant>/<suffix>' where registrant is 4-9 digits and suffix is any non-whitespace characters. Examples: 10.1000/journal.pone.0001, 10.18730/9WQ$D, 10.1000/\u00e9dition",
               "pattern": "^10\\.\\d{4,9}/\\S+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "doi",
               "default": "doi",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "DOIIdentifier",
         "type": "object"
      },
      "DriverVersion": {
         "description": "The version based on the DRIVER guidelines versioning scheme.\n\n(Borrowed from OpenAlex)",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "type": "string"
      },
      "DuplicateDetermination": {
         "description": "The determination of whether a reference is a duplicate.\n\nThis encodes both a status and a determination.",
         "enum": [
            "pending",
            "nominated",
            "duplicate",
            "exact_duplicate",
            "canonical",
            "unresolved",
            "unsearchable",
            "decoupled"
         ],
         "title": "DuplicateDetermination",
         "type": "string"
      },
      "ERICIdentifier": {
         "description": "An external identifier representing an ERIC Number.\n\nAn ERIC Number is defined as a unique identifying number preceded by\nED (for a non-journal document) or EJ (for a journal article).",
         "properties": {
            "identifier": {
               "description": "The ERIC Number. Format: 'ED' or 'EJ' followed by digits. Example: ED123456 or EJ789012",
               "pattern": "E[D|J][0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "eric",
               "default": "eric",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ERICIdentifier",
         "type": "object"
      },
      "Enhancement": {
         "description": "Core enhancement model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "created_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp at which the object was created.",
               "title": "Created At"
            },
            "updated_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp at which the object was last updated.",
               "title": "Updated At"
            },
            "source": {
               "description": "The enhancement source for tracking provenance.",
               "title": "Source",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "description": "The level of visibility of the enhancement"
            },
            "robot_version": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version of the robot that generated the content.",
               "title": "Robot Version"
            },
            "derived_from": {
               "anyOf": [
                  {
                     "items": {
                        "format": "uuid",
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of enhancement IDs that this enhancement was derived from.",
               "title": "Derived From"
            },
            "content": {
               "description": "The content of the enhancement.",
               "discriminator": {
                  "mapping": {
                     "abstract": "#/$defs/AbstractContentEnhancement",
                     "annotation": "#/$defs/AnnotationEnhancement",
                     "bibliographic": "#/$defs/BibliographicMetadataEnhancement",
                     "full_text": "#/$defs/FullTextEnhancement",
                     "linked_data": "#/$defs/LinkedDataEnhancement",
                     "location": "#/$defs/LocationEnhancement",
                     "raw": "#/$defs/RawEnhancement",
                     "reference_association": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LinkedDataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/FullTextEnhancement"
                  },
                  {
                     "$ref": "#/$defs/RawEnhancement"
                  }
               ],
               "title": "Content"
            },
            "reference_id": {
               "description": "The ID of the reference this enhancement is associated with.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The reference this enhancement is associated with."
            }
         },
         "required": [
            "source",
            "visibility",
            "content",
            "reference_id"
         ],
         "title": "Enhancement",
         "type": "object"
      },
      "FullTextEnhancement": {
         "description": "An enhancement for storing a link to the full text and its metadata.\n\nWe separate this from the SDK model as it contains a file pointer, not\nthe URL to the file itself.",
         "properties": {
            "enhancement_type": {
               "const": "full_text",
               "default": "full_text",
               "title": "Enhancement Type",
               "type": "string"
            },
            "blob": {
               "$ref": "#/$defs/BlobStorageFile",
               "description": "Blob storage pointer to the full text file."
            },
            "byte_size": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Size of the file in bytes. If provided on import, will be used to validate the file size. Will always be present on enhancements from the repository.",
               "title": "Byte Size"
            },
            "sha256_checksum": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "SHA256 checksum of the file. If provided on import, will be used to verify the integrity of the file. Will always be present on enhancements from the repository.",
               "title": "Sha256 Checksum"
            },
            "mime_type": {
               "default": "application/pdf",
               "description": "The MIME type of the file.",
               "title": "Mime Type",
               "type": "string"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version (according to the DRIVER versioning scheme) of this full text."
            },
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "If this full text is Open Access. May be left as null if this is unknown.",
               "title": "Is Oa"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The publishing license for this full text.",
               "examples": [
                  "apache-2-0",
                  "cc-by",
                  "cc-by-nc",
                  "cc-by-nc-nd",
                  "cc-by-nc-sa",
                  "cc-by-nd",
                  "cc-by-sa",
                  "gpl-v2",
                  "gpl-v3",
                  "isc",
                  "mit",
                  "other-oa",
                  "public-domain"
               ],
               "title": "License"
            },
            "source": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The source from which this full text was obtained.",
               "title": "Source"
            },
            "source_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The URL of the source from which this full text was obtained.",
               "title": "Source Url"
            },
            "retrieved_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp when this full text was retrieved.",
               "title": "Retrieved At"
            }
         },
         "required": [
            "blob"
         ],
         "title": "FullTextEnhancement",
         "type": "object"
      },
      "JsonValue": {},
      "LinkedDataEnhancement": {
         "description": "An enhancement for storing structured data in a linked data format.\n\nThe content is a JSON-LD document conforming to the vocabulary and\ncontext specified. This enhancement type is produced by mapping robots\nthat transform RawEnhancement data into the shared vocabulary.",
         "properties": {
            "enhancement_type": {
               "const": "linked_data",
               "default": "linked_data",
               "title": "Enhancement Type",
               "type": "string"
            },
            "vocabulary_uri": {
               "description": "The URI of the vocabulary against which this data was produced. Used for compatibility checking.",
               "examples": [
                  "https://vocab.evrepo.org/vocabulary/v1"
               ],
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "Vocabulary Uri",
               "type": "string"
            },
            "data": {
               "additionalProperties": {
                  "$ref": "#/$defs/JsonValue"
               },
               "description": "The JSON-LD content. Must contain an '@context' key with a valid URI string. When combined with the @context, this forms a complete linked data graph.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "vocabulary_uri",
            "data"
         ],
         "title": "LinkedDataEnhancement",
         "type": "object"
      },
      "LinkedExternalIdentifier": {
         "description": "External identifier model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "identifier": {
               "description": "The identifier itself.",
               "discriminator": {
                  "mapping": {
                     "doi": "#/$defs/DOIIdentifier",
                     "eric": "#/$defs/ERICIdentifier",
                     "open_alex": "#/$defs/OpenAlexIdentifier",
                     "other": "#/$defs/OtherIdentifier",
                     "pm_id": "#/$defs/PubMedIdentifier",
                     "pro_quest": "#/$defs/ProQuestIdentifier"
                  },
                  "propertyName": "identifier_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/DOIIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ERICIdentifier"
                  },
                  {
                     "$ref": "#/$defs/PubMedIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ProQuestIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OpenAlexIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OtherIdentifier"
                  }
               ],
               "title": "Identifier"
            },
            "reference_id": {
               "description": "The ID of the reference this identifier identifies.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The reference this identifier identifies."
            }
         },
         "required": [
            "identifier",
            "reference_id"
         ],
         "title": "LinkedExternalIdentifier",
         "type": "object"
      },
      "Location": {
         "description": "A location where a reference can be found.\n\nThis maps almost completely to the OpenAlex\n[Location object](https://docs.openalex.org/api-entities/works/work-object/location-object)",
         "properties": {
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): True if an Open Access (OA) version of this work is available\nat this location. May be left as null if this is unknown (and thus)\ntreated effectively as `false`.\n",
               "title": "Is Oa"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\nThe version (according to the DRIVER versioning scheme) of this location.\n"
            },
            "landing_page_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "(From OpenAlex): The landing page URL for this location.",
               "title": "Landing Page Url"
            },
            "pdf_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): A URL where you can find this location as a PDF.\n",
               "title": "Pdf Url"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): The location's publishing license. This can be a Creative\nCommons license such as cc0 or cc-by, a publisher-specific license, or null\nwhich means we are not able to determine a license for this location.\n",
               "title": "License"
            },
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Any extra metadata about this location",
               "title": "Extra"
            }
         },
         "title": "Location",
         "type": "object"
      },
      "LocationEnhancement": {
         "description": "An enhancement which describes locations where this reference can be found.\n\nThis maps closely (almost exactly) to OpenAlex's locations.",
         "properties": {
            "enhancement_type": {
               "const": "location",
               "default": "location",
               "title": "Enhancement Type",
               "type": "string"
            },
            "locations": {
               "description": "A list of locations where this reference can be found.",
               "items": {
                  "$ref": "#/$defs/Location"
               },
               "minItems": 1,
               "title": "Locations",
               "type": "array"
            }
         },
         "required": [
            "locations"
         ],
         "title": "LocationEnhancement",
         "type": "object"
      },
      "OpenAlexIdentifier": {
         "description": "An external identifier representing an OpenAlex ID.",
         "properties": {
            "identifier": {
               "description": "The OpenAlex ID of the reference. Format: 'W' followed by digits. Example: W2741809807",
               "pattern": "^W\\d+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "open_alex",
               "default": "open_alex",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "OpenAlexIdentifier",
         "type": "object"
      },
      "OtherIdentifier": {
         "description": "An external identifier not otherwise defined by the repository.",
         "properties": {
            "identifier": {
               "description": "The identifier of the reference.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "other",
               "default": "other",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            },
            "other_identifier_name": {
               "description": "The name of the undocumented identifier type.",
               "title": "Other Identifier Name",
               "type": "string"
            }
         },
         "required": [
            "identifier",
            "other_identifier_name"
         ],
         "title": "OtherIdentifier",
         "type": "object"
      },
      "Pagination": {
         "description": "Pagination information for journal articles.\n\nMaps to OpenAlex's work.biblio object. All fields are strings to match\nOpenAlex's format, which may include non-numeric values like \"Spring\" or \"A1\".",
         "properties": {
            "volume": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The volume number of the journal/publication.",
               "title": "Volume"
            },
            "issue": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The issue number of the journal/publication.",
               "title": "Issue"
            },
            "first_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The first page number of the reference in the publication.",
               "title": "First Page"
            },
            "last_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The last page number of the reference in the publication.",
               "title": "Last Page"
            }
         },
         "title": "Pagination",
         "type": "object"
      },
      "ProQuestIdentifier": {
         "description": "An external identifier representing a ProQuest ID.",
         "properties": {
            "identifier": {
               "description": "The ProQuest ID of the reference. Format: numeric digits only. Example: 12345678",
               "pattern": "[0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "pro_quest",
               "default": "pro_quest",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ProQuestIdentifier",
         "type": "object"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID (PMID) of the reference. Example: 12345678",
               "exclusiveMinimum": 0,
               "title": "Identifier",
               "type": "integer"
            },
            "identifier_type": {
               "const": "pm_id",
               "default": "pm_id",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "PubMedIdentifier",
         "type": "object"
      },
      "PublicationVenue": {
         "description": "A publication venue (journal, repository, conference, etc.).",
         "properties": {
            "display_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The display name of the venue (journal name, repository name, etc.)",
               "title": "Display Name"
            },
            "venue_type": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenueType"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The type of venue: journal, repository, book, conference, etc."
            },
            "issn": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of ISSNs associated with this venue (print and electronic)",
               "title": "Issn"
            },
            "issn_l": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The linking ISSN - a canonical ISSN for the venue across format changes",
               "title": "Issn L"
            },
            "host_organization_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Display name of the host organization (publisher)",
               "title": "Host Organization Name"
            }
         },
         "title": "PublicationVenue",
         "type": "object"
      },
      "PublicationVenueType": {
         "description": "Type of publication venue.\n\nAligns with OpenAlex source types.",
         "enum": [
            "journal",
            "repository",
            "conference",
            "ebook_platform",
            "book_series",
            "other"
         ],
         "title": "PublicationVenueType",
         "type": "string"
      },
      "RawEnhancement": {
         "description": "An enhancement for storing raw/arbitrary/unstructured data.\n\nData in these enhancements is intended for future conversion into structured form.\n\nThis enhancement accepts any fields passed in to `data`. These enhancements cannot\nbe created by robots.",
         "properties": {
            "enhancement_type": {
               "const": "raw",
               "default": "raw",
               "title": "Enhancement Type",
               "type": "string"
            },
            "source_export_date": {
               "description": "Date the enhancement data was retrieved.",
               "format": "date-time",
               "title": "Source Export Date",
               "type": "string"
            },
            "description": {
               "description": "Description of the data to aid in future refinement.",
               "title": "Description",
               "type": "string"
            },
            "metadata": {
               "additionalProperties": true,
               "description": "Additional metadata to aid in future structuring of raw data",
               "title": "Metadata",
               "type": "object"
            },
            "data": {
               "description": "Unstructured data for later processing.",
               "title": "Data"
            }
         },
         "required": [
            "source_export_date",
            "description",
            "data"
         ],
         "title": "RawEnhancement",
         "type": "object"
      },
      "Reference": {
         "description": "Core reference model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "default": "public",
               "description": "The level of visibility of the reference"
            },
            "identifiers": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/LinkedExternalIdentifier"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `LinkedExternalIdentifiers` for the Reference",
               "title": "Identifiers"
            },
            "enhancements": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Enhancement"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of enhancements for the reference",
               "title": "Enhancements"
            },
            "duplicate_decision": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/ReferenceDuplicateDecision"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The current active duplicate decision for this reference. If None, either duplicate_decision has not been preloaded or the duplicate status is pending."
            },
            "canonical_reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The canonical reference that this reference is a duplicate of"
            },
            "duplicate_references": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Reference"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of references that this reference duplicates",
               "title": "Duplicate References"
            }
         },
         "title": "Reference",
         "type": "object"
      },
      "ReferenceAssociationEnhancement": {
         "description": "An enhancement for storing associations between references.",
         "properties": {
            "enhancement_type": {
               "const": "reference_association",
               "default": "reference_association",
               "title": "Enhancement Type",
               "type": "string"
            },
            "associated_reference_ids": {
               "description": "A list of Identifiers which are associated to this reference. These can either be ExternalIdentifiers or resolved repository UUID4s.",
               "items": {
                  "anyOf": [
                     {
                        "discriminator": {
                           "mapping": {
                              "doi": "#/$defs/DOIIdentifier",
                              "eric": "#/$defs/ERICIdentifier",
                              "open_alex": "#/$defs/OpenAlexIdentifier",
                              "other": "#/$defs/OtherIdentifier",
                              "pm_id": "#/$defs/PubMedIdentifier",
                              "pro_quest": "#/$defs/ProQuestIdentifier"
                           },
                           "propertyName": "identifier_type"
                        },
                        "oneOf": [
                           {
                              "$ref": "#/$defs/DOIIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ERICIdentifier"
                           },
                           {
                              "$ref": "#/$defs/PubMedIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ProQuestIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OpenAlexIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OtherIdentifier"
                           }
                        ]
                     },
                     {
                        "anyOf": [
                           {
                              "format": "uuid4",
                              "type": "string"
                           },
                           {
                              "format": "uuid7",
                              "type": "string"
                           }
                        ],
                        "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
                     }
                  ]
               },
               "minItems": 1,
               "title": "Associated Reference Ids",
               "type": "array"
            },
            "association_type": {
               "$ref": "#/$defs/ReferenceAssociationType",
               "description": "The type of association between this reference and the associated ones. Direction is important: \"this reference <association_type> associated reference\"."
            }
         },
         "required": [
            "associated_reference_ids",
            "association_type"
         ],
         "title": "ReferenceAssociationEnhancement",
         "type": "object"
      },
      "ReferenceAssociationType": {
         "description": "The type of association between references.\n\nDirection is important: \"this reference <association_type> associated reference\".",
         "enum": [
            "cites",
            "is_cited_by",
            "is_similar_to"
         ],
         "title": "ReferenceAssociationType",
         "type": "string"
      },
      "ReferenceDuplicateDecision": {
         "description": "Model representing a decision on whether a reference is a duplicate.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "reference_id": {
               "description": "The ID of the reference being evaluated.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "enhancement_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the enhancement that triggered this duplicate decision, if any.",
               "title": "Enhancement Id"
            },
            "active_decision": {
               "default": false,
               "description": "Whether this is the active decision for the reference.",
               "title": "Active Decision",
               "type": "boolean"
            },
            "candidate_canonical_ids": {
               "description": "A list of candidate canonical IDs for the reference.",
               "items": {
                  "format": "uuid",
                  "type": "string"
               },
               "title": "Candidate Canonical Ids",
               "type": "array"
            },
            "duplicate_determination": {
               "$ref": "#/$defs/DuplicateDetermination",
               "default": "pending",
               "description": "The duplicate status of the reference."
            },
            "canonical_reference_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the canonical reference this reference duplicates.",
               "title": "Canonical Reference Id"
            },
            "detail": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Optional additional detail about the decision.",
               "title": "Detail"
            }
         },
         "required": [
            "reference_id"
         ],
         "title": "ReferenceDuplicateDecision",
         "type": "object"
      },
      "ScoreAnnotation": {
         "description": "An annotation which represents the score for a label.\n\nThis is similar to a BooleanAnnotation, but lacks a boolean determination\nas to the application of the label.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "score": {
               "description": "Score for this annotation",
               "title": "Score",
               "type": "number"
            },
            "data": {
               "additionalProperties": true,
               "description": "An object representation of the annotation including any confidence scores or descriptions.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "score"
         ],
         "title": "ScoreAnnotation",
         "type": "object"
      },
      "Visibility": {
         "description": "The visibility of a data element in the repository.\n\nThis is used to manage whether information should be publicly available or\nrestricted (generally due to copyright constraints from publishers).\n\nTODO: Implement data governance layer to manage this.",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   },
   "$ref": "#/$defs/Reference"
}

Config:

• from_attributes: bool = True

Fields:

• canonical_reference (app.domain.references.models.models.Reference | None)

• duplicate_decision (app.domain.references.models.models.ReferenceDuplicateDecision | None)

• duplicate_references (list[app.domain.references.models.models.Reference] | None)

• enhancements (list[app.domain.references.models.models.Enhancement] | None)

• id (uuid.UUID)

• identifiers (list[app.domain.references.models.models.LinkedExternalIdentifier] | None)

• visibility (app.domain.references.models.models.Visibility)

field canonical_reference: Reference | None = None

The canonical reference that this reference is a duplicate of

field duplicate_decision: ReferenceDuplicateDecision | None = None

The current active duplicate decision for this reference. If None, either duplicate_decision has not been preloaded or the duplicate status is pending.

field duplicate_references: list[Reference] | None = None

A list of references that this reference duplicates

field enhancements: list[Enhancement] | None = None

A list of enhancements for the reference

field id: UUID [Optional]

The autogenerated database ID.

field identifiers: list[LinkedExternalIdentifier] | None = None

A list of LinkedExternalIdentifiers for the Reference

field visibility: Visibility = Visibility.PUBLIC

The level of visibility of the reference

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

is_superset(reference: Reference) → bool

Check if this Reference is a superset of the given Reference.

This compares enhancements, identifiers and visibility, removing persistence differences (eg database ids), to verify if the content is identical. If the given Reference has anything unique, this will return False.

Parameters:

reference (Reference) – The reference to compare against.

Returns:

True if the given Reference is a subset of this Reference, else False.

Return type:

bool

property has_duplicates: bool | None

Whether this reference has any duplicate references pointing to it.

Will return None if duplicate references are not preloaded.

property is_canonical: bool | None

Pessimistically check if this reference is the canonical version.

Returns None if no duplicate decision is present, either due to not being preloaded or still pending.

property is_canonical_like: bool

Optimistically check if this reference is the canonical version.

Only returns False if the reference is a determined duplicate. Pending, unresolved and not-preloaded duplicate decisions are treated as canonical-like.

pydantic model app.domain.references.models.models.ReferenceDuplicateDecision

Model representing a decision on whether a reference is a duplicate.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ReferenceDuplicateDecision",
   "description": "Model representing a decision on whether a reference is a duplicate.",
   "type": "object",
   "properties": {
      "id": {
         "description": "The autogenerated database ID.",
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "reference_id": {
         "description": "The ID of the reference being evaluated.",
         "format": "uuid",
         "title": "Reference Id",
         "type": "string"
      },
      "enhancement_id": {
         "anyOf": [
            {
               "format": "uuid",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The ID of the enhancement that triggered this duplicate decision, if any.",
         "title": "Enhancement Id"
      },
      "active_decision": {
         "default": false,
         "description": "Whether this is the active decision for the reference.",
         "title": "Active Decision",
         "type": "boolean"
      },
      "candidate_canonical_ids": {
         "description": "A list of candidate canonical IDs for the reference.",
         "items": {
            "format": "uuid",
            "type": "string"
         },
         "title": "Candidate Canonical Ids",
         "type": "array"
      },
      "duplicate_determination": {
         "$ref": "#/$defs/DuplicateDetermination",
         "default": "pending",
         "description": "The duplicate status of the reference."
      },
      "canonical_reference_id": {
         "anyOf": [
            {
               "format": "uuid",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The ID of the canonical reference this reference duplicates.",
         "title": "Canonical Reference Id"
      },
      "detail": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Optional additional detail about the decision.",
         "title": "Detail"
      }
   },
   "$defs": {
      "DuplicateDetermination": {
         "description": "The determination of whether a reference is a duplicate.\n\nThis encodes both a status and a determination.",
         "enum": [
            "pending",
            "nominated",
            "duplicate",
            "exact_duplicate",
            "canonical",
            "unresolved",
            "unsearchable",
            "decoupled"
         ],
         "title": "DuplicateDetermination",
         "type": "string"
      }
   },
   "required": [
      "reference_id"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• active_decision (bool)

• candidate_canonical_ids (list[uuid.UUID])

• canonical_reference_id (uuid.UUID | None)

• detail (str | None)

• duplicate_determination (app.domain.references.models.models.DuplicateDetermination)

• enhancement_id (uuid.UUID | None)

• id (uuid.UUID)

• reference_id (uuid.UUID)

Validators:

• check_active_decision_is_terminal » all fields

• check_canonical_reference_id_populated_iff_duplicate » all fields

field active_decision: bool = False

Whether this is the active decision for the reference.

Validated by:

• check_active_decision_is_terminal

• check_canonical_reference_id_populated_iff_duplicate

field candidate_canonical_ids: list[UUID] [Optional]

A list of candidate canonical IDs for the reference.

Validated by:

• check_active_decision_is_terminal

• check_canonical_reference_id_populated_iff_duplicate

field canonical_reference_id: UUID | None = None

The ID of the canonical reference this reference duplicates.

Validated by:

• check_active_decision_is_terminal

• check_canonical_reference_id_populated_iff_duplicate

field detail: str | None = None

Optional additional detail about the decision.

Validated by:

• check_active_decision_is_terminal

• check_canonical_reference_id_populated_iff_duplicate

field duplicate_determination: DuplicateDetermination = DuplicateDetermination.PENDING

The duplicate status of the reference.

Validated by:

• check_active_decision_is_terminal

• check_canonical_reference_id_populated_iff_duplicate

field enhancement_id: UUID | None = None

The ID of the enhancement that triggered this duplicate decision, if any.

Validated by:

• check_active_decision_is_terminal

• check_canonical_reference_id_populated_iff_duplicate

field id: UUID [Optional]

The autogenerated database ID.

Validated by:

• check_active_decision_is_terminal

• check_canonical_reference_id_populated_iff_duplicate

field reference_id: UUID [Required]

The ID of the reference being evaluated.

Validated by:

• check_active_decision_is_terminal

• check_canonical_reference_id_populated_iff_duplicate

validator check_active_decision_is_terminal  »  all fields

Assert that active decisions are only set for terminal states.

validator check_canonical_reference_id_populated_iff_duplicate  »  all fields

Assert that canonical must exist if and only if decision is duplicate.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

pydantic model app.domain.references.models.models.ReferenceDuplicateDeterminationResult

Model representing the result of a duplicate determination.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ReferenceDuplicateDeterminationResult",
   "description": "Model representing the result of a duplicate determination.",
   "type": "object",
   "properties": {
      "duplicate_determination": {
         "enum": [
            "canonical",
            "duplicate",
            "unresolved",
            "unsearchable"
         ],
         "title": "Duplicate Determination",
         "type": "string"
      },
      "canonical_reference_id": {
         "anyOf": [
            {
               "format": "uuid",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The ID of the determined canonical reference.",
         "title": "Canonical Reference Id"
      },
      "detail": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Optional detail about the determination process, particularly where the determination is UNRESOLVED or UNSEARCHABLE.",
         "title": "Detail"
      }
   },
   "required": [
      "duplicate_determination"
   ]
}

Fields:

• canonical_reference_id (uuid.UUID | None)

• detail (str | None)

• duplicate_determination (Literal[app.domain.references.models.models.DuplicateDetermination.CANONICAL, app.domain.references.models.models.DuplicateDetermination.DUPLICATE, app.domain.references.models.models.DuplicateDetermination.UNRESOLVED, app.domain.references.models.models.DuplicateDetermination.UNSEARCHABLE])

Validators:

• check_canonical_reference_id_populated_iff_duplicate » all fields

field canonical_reference_id: UUID | None = None

The ID of the determined canonical reference.

Validated by:

• check_canonical_reference_id_populated_iff_duplicate

field detail: str | None = None

Optional detail about the determination process, particularly where the determination is UNRESOLVED or UNSEARCHABLE.

Validated by:

• check_canonical_reference_id_populated_iff_duplicate

field duplicate_determination: Literal[DuplicateDetermination.CANONICAL, DuplicateDetermination.DUPLICATE, DuplicateDetermination.UNRESOLVED, DuplicateDetermination.UNSEARCHABLE] [Required]

Validated by:

• check_canonical_reference_id_populated_iff_duplicate

validator check_canonical_reference_id_populated_iff_duplicate  »  all fields

Assert that canonical must exist if and only if decision is duplicate.

pydantic model app.domain.references.models.models.ReferenceExport

A queued job that produces a file of an explicit list of references.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ReferenceExport",
   "description": "A queued job that produces a file of an explicit list of references.",
   "type": "object",
   "properties": {
      "id": {
         "description": "The autogenerated database ID.",
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "export_format": {
         "$ref": "#/$defs/ExportFormat",
         "default": "jsonl",
         "description": "The serialization format of the produced file."
      },
      "status": {
         "$ref": "#/$defs/ExportStatus",
         "default": "pending",
         "description": "The current status of the export job."
      },
      "result_file": {
         "anyOf": [
            {
               "$ref": "#/$defs/BlobStorageFile"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The file produced by the job, once completed."
      },
      "n_references": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The number of references in the produced file.",
         "title": "N References"
      },
      "error": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Error message, if the job failed.",
         "title": "Error"
      },
      "reference_ids": {
         "description": "The references to export.",
         "items": {
            "format": "uuid",
            "type": "string"
         },
         "title": "Reference Ids",
         "type": "array"
      }
   },
   "$defs": {
      "BlobStorageFile": {
         "description": "Model to represent Blob Storage files.",
         "properties": {
            "location": {
               "$ref": "#/$defs/BlobStorageLocation",
               "description": "The location of the blob storage."
            },
            "container": {
               "description": "The name of the container in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in blob storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio",
            "http",
            "https"
         ],
         "title": "BlobStorageLocation",
         "type": "string"
      },
      "ExportFormat": {
         "description": "The serialization format of a reference export.",
         "enum": [
            "jsonl",
            "ris"
         ],
         "title": "ExportFormat",
         "type": "string"
      },
      "ExportStatus": {
         "description": "The status of an export job.",
         "enum": [
            "pending",
            "running",
            "completed",
            "failed"
         ],
         "title": "ExportStatus",
         "type": "string"
      }
   },
   "required": [
      "reference_ids"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• error ()

• export_format ()

• id ()

• n_references ()

• reference_ids (list[uuid.UUID])

• result_file ()

• status ()

field error: str | None = None

Error message, if the job failed.

field export_format: ExportFormat = ExportFormat.JSONL

The serialization format of the produced file.

field id: UUID [Optional]

The autogenerated database ID.

field n_references: int | None = None

The number of references in the produced file.

field reference_ids: list[UUID] [Required]

The references to export.

field result_file: BlobStorageFile | None = None

The file produced by the job, once completed.

field status: ExportStatus = ExportStatus.PENDING

The current status of the export job.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

pydantic model app.domain.references.models.models.ReferenceIds

Model representing a list of reference IDs.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ReferenceIds",
   "description": "Model representing a list of reference IDs.",
   "type": "object",
   "properties": {
      "reference_ids": {
         "description": "A list of reference IDs.",
         "items": {
            "format": "uuid",
            "type": "string"
         },
         "title": "Reference Ids",
         "type": "array"
      }
   },
   "required": [
      "reference_ids"
   ]
}

Fields:

• reference_ids (list[uuid.UUID])

field reference_ids: list[UUID] [Required]

A list of reference IDs.

pydantic model app.domain.references.models.models.ReferenceSearchFields

Projection representing fields used for searching references.

This model is a projection of app.domain.references.models.models.Reference.

This is injected into the root of Elasticsearch Reference documents for easy searching.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ReferenceSearchFields",
   "description": "Projection representing fields used for searching references.\n\nThis model is a projection of\n:class:`app.domain.references.models.models.Reference`.\n\nThis is injected into the root of Elasticsearch Reference documents for easy\nsearching.",
   "type": "object",
   "properties": {
      "abstract": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The abstract of the reference.",
         "title": "Abstract"
      },
      "authors": {
         "description": "The authors of the reference.",
         "items": {
            "type": "string"
         },
         "title": "Authors",
         "type": "array"
      },
      "publication_date": {
         "anyOf": [
            {
               "format": "date",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The publication date of the reference.",
         "title": "Publication Date"
      },
      "publication_year": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The publication year of the reference.",
         "title": "Publication Year"
      },
      "title": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The title of the reference.",
         "title": "Title"
      },
      "annotations": {
         "description": "List of true annotations on the reference.Each annotation is in the format `<scheme>/<label>`.",
         "items": {
            "type": "string"
         },
         "title": "Annotations",
         "type": "array"
      },
      "evaluated_schemes": {
         "description": "List of annotation schemes that have been evaluated on the reference.",
         "items": {
            "type": "string"
         },
         "title": "Evaluated Schemes",
         "type": "array"
      },
      "destiny_inclusion_score": {
         "anyOf": [
            {
               "type": "number"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The inclusion score on the destiny domain inclusion annotation, if evaluated.",
         "title": "Destiny Inclusion Score"
      },
      "linked_data_content": {
         "anyOf": [
            {
               "$ref": "#/$defs/LinkedDataEnhancement"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The content of the highest-priority LINKED_DATA enhancement, if any. This is the raw enhancement content before projection into searchable concepts and labels."
      }
   },
   "$defs": {
      "JsonValue": {},
      "LinkedDataEnhancement": {
         "description": "An enhancement for storing structured data in a linked data format.\n\nThe content is a JSON-LD document conforming to the vocabulary and\ncontext specified. This enhancement type is produced by mapping robots\nthat transform RawEnhancement data into the shared vocabulary.",
         "properties": {
            "enhancement_type": {
               "const": "linked_data",
               "default": "linked_data",
               "title": "Enhancement Type",
               "type": "string"
            },
            "vocabulary_uri": {
               "description": "The URI of the vocabulary against which this data was produced. Used for compatibility checking.",
               "examples": [
                  "https://vocab.evrepo.org/vocabulary/v1"
               ],
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "Vocabulary Uri",
               "type": "string"
            },
            "data": {
               "additionalProperties": {
                  "$ref": "#/$defs/JsonValue"
               },
               "description": "The JSON-LD content. Must contain an '@context' key with a valid URI string. When combined with the @context, this forms a complete linked data graph.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "vocabulary_uri",
            "data"
         ],
         "title": "LinkedDataEnhancement",
         "type": "object"
      }
   }
}

Fields:

• abstract (str | None)

• annotations (list[str])

• authors (list[str])

• destiny_inclusion_score (float | None)

• evaluated_schemes (list[str])

• linked_data_content (destiny_sdk.enhancements.LinkedDataEnhancement | None)

• publication_date (datetime.date | None)

• publication_year (int | None)

• title (str | None)

Validators:

• normalise_string_list_validator » annotations

• normalise_string_list_validator » authors

• normalise_string_list_validator » evaluated_schemes

• normalise_string_validator » abstract

• normalise_string_validator » title

field abstract: str | None = None

The abstract of the reference.

Validated by:

• normalise_string_validator

field annotations: list[str] [Optional]

List of true annotations on the reference.Each annotation is in the format <scheme>/<label>.

Validated by:

• normalise_string_list_validator

field authors: list[str] [Optional]

The authors of the reference.

Validated by:

• normalise_string_list_validator

field destiny_inclusion_score: float | None = None

The inclusion score on the destiny domain inclusion annotation, if evaluated.

field evaluated_schemes: list[str] [Optional]

List of annotation schemes that have been evaluated on the reference.

Validated by:

• normalise_string_list_validator

field linked_data_content: LinkedDataEnhancement | None = None

The content of the highest-priority LINKED_DATA enhancement, if any. This is the raw enhancement content before projection into searchable concepts and labels.

field publication_date: date | None = None

The publication date of the reference.

field publication_year: int | None = None

The publication year of the reference.

field title: str | None = None

The title of the reference.

Validated by:

• normalise_string_validator

validator normalise_string_list_validator  »  authors, evaluated_schemes, annotations

Normalise string list fields by stripping whitespace.

validator normalise_string_validator  »  abstract, title

Normalise string fields by stripping whitespace.

to_canonical_candidate_search_fields() → CandidateCanonicalSearchFields

Return fields needed for candidate canonical selection.

pydantic model app.domain.references.models.models.ReferenceSearchProjection

Pre-computed projection of a Reference for ES indexing.

Contains only the fields that ES indexes, constructed by the synchronizer from a Reference and its projections. Inherits SQLAttributeMixin for the id field and to satisfy the GenericDomainModelType bound required by the ES persistence layer.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ReferenceSearchProjection",
   "description": "Pre-computed projection of a Reference for ES indexing.\n\nContains only the fields that ES indexes, constructed by the synchronizer\nfrom a Reference and its projections. Inherits SQLAttributeMixin for the\nid field and to satisfy the GenericDomainModelType bound required by the\nES persistence layer.",
   "type": "object",
   "properties": {
      "id": {
         "description": "The autogenerated database ID.",
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "visibility": {
         "$ref": "#/$defs/Visibility",
         "description": "The level of visibility of the reference."
      },
      "duplicate_determination": {
         "anyOf": [
            {
               "$ref": "#/$defs/DuplicateDetermination"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The duplicate determination, if any."
      },
      "search_fields": {
         "$ref": "#/$defs/ReferenceSearchFields",
         "description": "Pre-computed search fields for Elasticsearch indexing."
      },
      "linked_data_projection": {
         "anyOf": [
            {
               "$ref": "#/$defs/LinkedDataProjection"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Pre-computed linked data projection, if any."
      }
   },
   "$defs": {
      "DuplicateDetermination": {
         "description": "The determination of whether a reference is a duplicate.\n\nThis encodes both a status and a determination.",
         "enum": [
            "pending",
            "nominated",
            "duplicate",
            "exact_duplicate",
            "canonical",
            "unresolved",
            "unsearchable",
            "decoupled"
         ],
         "title": "DuplicateDetermination",
         "type": "string"
      },
      "JsonValue": {},
      "LinkedDataEnhancement": {
         "description": "An enhancement for storing structured data in a linked data format.\n\nThe content is a JSON-LD document conforming to the vocabulary and\ncontext specified. This enhancement type is produced by mapping robots\nthat transform RawEnhancement data into the shared vocabulary.",
         "properties": {
            "enhancement_type": {
               "const": "linked_data",
               "default": "linked_data",
               "title": "Enhancement Type",
               "type": "string"
            },
            "vocabulary_uri": {
               "description": "The URI of the vocabulary against which this data was produced. Used for compatibility checking.",
               "examples": [
                  "https://vocab.evrepo.org/vocabulary/v1"
               ],
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "Vocabulary Uri",
               "type": "string"
            },
            "data": {
               "additionalProperties": {
                  "$ref": "#/$defs/JsonValue"
               },
               "description": "The JSON-LD content. Must contain an '@context' key with a valid URI string. When combined with the @context, this forms a complete linked data graph.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "vocabulary_uri",
            "data"
         ],
         "title": "LinkedDataEnhancement",
         "type": "object"
      },
      "LinkedDataProjection": {
         "description": "Result of projecting a LinkedDataEnhancement into flat searchable fields.",
         "properties": {
            "concepts": {
               "items": {
                  "type": "string"
               },
               "title": "Concepts",
               "type": "array",
               "uniqueItems": true
            },
            "labels": {
               "items": {
                  "type": "string"
               },
               "title": "Labels",
               "type": "array",
               "uniqueItems": true
            },
            "evaluated_properties": {
               "items": {
                  "type": "string"
               },
               "title": "Evaluated Properties",
               "type": "array",
               "uniqueItems": true
            },
            "countries": {
               "items": {
                  "type": "string"
               },
               "title": "Countries",
               "type": "array",
               "uniqueItems": true
            },
            "country_wb_regions": {
               "items": {
                  "type": "string"
               },
               "title": "Country Wb Regions",
               "type": "array",
               "uniqueItems": true
            }
         },
         "title": "LinkedDataProjection",
         "type": "object"
      },
      "ReferenceSearchFields": {
         "description": "Projection representing fields used for searching references.\n\nThis model is a projection of\n:class:`app.domain.references.models.models.Reference`.\n\nThis is injected into the root of Elasticsearch Reference documents for easy\nsearching.",
         "properties": {
            "abstract": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The abstract of the reference.",
               "title": "Abstract"
            },
            "authors": {
               "description": "The authors of the reference.",
               "items": {
                  "type": "string"
               },
               "title": "Authors",
               "type": "array"
            },
            "publication_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The publication date of the reference.",
               "title": "Publication Date"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The publication year of the reference.",
               "title": "Publication Year"
            },
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The title of the reference.",
               "title": "Title"
            },
            "annotations": {
               "description": "List of true annotations on the reference.Each annotation is in the format `<scheme>/<label>`.",
               "items": {
                  "type": "string"
               },
               "title": "Annotations",
               "type": "array"
            },
            "evaluated_schemes": {
               "description": "List of annotation schemes that have been evaluated on the reference.",
               "items": {
                  "type": "string"
               },
               "title": "Evaluated Schemes",
               "type": "array"
            },
            "destiny_inclusion_score": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The inclusion score on the destiny domain inclusion annotation, if evaluated.",
               "title": "Destiny Inclusion Score"
            },
            "linked_data_content": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/LinkedDataEnhancement"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The content of the highest-priority LINKED_DATA enhancement, if any. This is the raw enhancement content before projection into searchable concepts and labels."
            }
         },
         "title": "ReferenceSearchFields",
         "type": "object"
      },
      "Visibility": {
         "description": "The visibility of a data element in the repository.\n\nThis is used to manage whether information should be publicly available or\nrestricted (generally due to copyright constraints from publishers).\n\nTODO: Implement data governance layer to manage this.",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   },
   "required": [
      "visibility",
      "search_fields"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• duplicate_determination (app.domain.references.models.models.DuplicateDetermination | None)

• id (uuid.UUID)

• linked_data_projection (app.domain.references.models.models.LinkedDataProjection | None)

• search_fields (app.domain.references.models.models.ReferenceSearchFields)

• visibility (app.domain.references.models.models.Visibility)

field duplicate_determination: DuplicateDetermination | None = None

The duplicate determination, if any.

field id: UUID [Optional]

The autogenerated database ID.

field linked_data_projection: LinkedDataProjection | None = None

Pre-computed linked data projection, if any.

field search_fields: ReferenceSearchFields [Required]

Pre-computed search fields for Elasticsearch indexing.

field visibility: Visibility [Required]

The level of visibility of the reference.

pydantic model app.domain.references.models.models.ReferenceSearchResult

Wrapping class for Elasticsearch search results.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ReferenceSearchResult",
   "description": "Wrapping class for Elasticsearch search results.",
   "type": "object",
   "properties": {
      "references": {
         "description": "The list of references returned from the search query.",
         "items": {
            "$ref": "#/$defs/Reference"
         },
         "title": "References",
         "type": "array"
      },
      "total": {
         "description": "The total number of results matching the search query.",
         "title": "Total",
         "type": "integer"
      },
      "page": {
         "description": "The page number of the results.",
         "title": "Page",
         "type": "integer"
      }
   },
   "$defs": {
      "AbstractContentEnhancement": {
         "description": "An enhancement which is specific to the abstract of a reference.\n\nThis is separate from the `BibliographicMetadata` for two reasons:\n\n1. Abstracts are increasingly missing from sources like OpenAlex, and may be\nbackfilled from other sources, without the bibliographic metadata.\n2. They are also subject to copyright limitations in ways which metadata are\nnot, and thus need separate visibility controls.",
         "properties": {
            "enhancement_type": {
               "const": "abstract",
               "default": "abstract",
               "title": "Enhancement Type",
               "type": "string"
            },
            "process": {
               "$ref": "#/$defs/AbstractProcessType"
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquire the abstract.",
         "enum": [
            "uninverted",
            "closed_api",
            "other"
         ],
         "title": "AbstractProcessType",
         "type": "string"
      },
      "AnnotationEnhancement": {
         "description": "An enhancement which is composed of a list of Annotations.",
         "properties": {
            "enhancement_type": {
               "const": "annotation",
               "default": "annotation",
               "title": "Enhancement Type",
               "type": "string"
            },
            "annotations": {
               "items": {
                  "discriminator": {
                     "mapping": {
                        "boolean": "#/$defs/BooleanAnnotation",
                        "score": "#/$defs/ScoreAnnotation"
                     },
                     "propertyName": "annotation_type"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/BooleanAnnotation"
                     },
                     {
                        "$ref": "#/$defs/ScoreAnnotation"
                     }
                  ]
               },
               "minItems": 1,
               "title": "Annotations",
               "type": "array"
            }
         },
         "required": [
            "annotations"
         ],
         "title": "AnnotationEnhancement",
         "type": "object"
      },
      "AuthorPosition": {
         "description": "The position of an author in a list of authorships.\n\nMaps to the data from OpenAlex.",
         "enum": [
            "first",
            "middle",
            "last"
         ],
         "title": "AuthorPosition",
         "type": "string"
      },
      "Authorship": {
         "description": "Represents a single author and their association with a reference.\n\nThis is a simplification of the OpenAlex [Authorship\nobject](https://docs.openalex.org/api-entities/works/work-object/authorship-object)\nfor our purposes.",
         "properties": {
            "display_name": {
               "description": "The display name of the author. Expected format FIRSTNAME <MIDDLENAME> LASTNAME. Providing display_name in an unexpected format will affect search performance.",
               "title": "Display Name",
               "type": "string"
            },
            "orcid": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ORCid of the author.",
               "title": "Orcid"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "position"
         ],
         "title": "Authorship",
         "type": "object"
      },
      "BibliographicMetadataEnhancement": {
         "description": "An enhancement which is made up of bibliographic metadata.\n\nGenerally this will be sourced from a database such as OpenAlex or similar.\nFor directly contributed references, these may not be complete.",
         "properties": {
            "enhancement_type": {
               "const": "bibliographic",
               "default": "bibliographic",
               "title": "Enhancement Type",
               "type": "string"
            },
            "authorship": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Authorship"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `Authorships` belonging to this reference.",
               "title": "Authorship"
            },
            "cited_by_count": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex) The number of citations to this work. These are the times that\nother works have cited this work\n",
               "title": "Cited By Count"
            },
            "created_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date this metadata record was created",
               "title": "Created Date"
            },
            "updated_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date of the last OpenAlex update to this metadata",
               "title": "Updated Date"
            },
            "publication_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The date which the version of record was published.",
               "title": "Publication Date"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The year in which the version of record was published.",
               "title": "Publication Year"
            },
            "publisher": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the entity which published the version of record.",
               "title": "Publisher"
            },
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The title of the reference.",
               "title": "Title"
            },
            "pagination": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Pagination"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Pagination info (volume, issue, pages)."
            },
            "publication_venue": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenue"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Publication venue information (journal, repository, etc.)."
            }
         },
         "title": "BibliographicMetadataEnhancement",
         "type": "object"
      },
      "BlobStorageFile": {
         "description": "Model to represent Blob Storage files.",
         "properties": {
            "location": {
               "$ref": "#/$defs/BlobStorageLocation",
               "description": "The location of the blob storage."
            },
            "container": {
               "description": "The name of the container in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in blob storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio",
            "http",
            "https"
         ],
         "title": "BlobStorageLocation",
         "type": "string"
      },
      "BooleanAnnotation": {
         "description": "An annotation is a way of tagging the content with a label of some kind.\n\nThis class will probably be broken up in the future, but covers most of our\ninitial cases.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "value": {
               "description": "Boolean flag for this annotation",
               "title": "Value",
               "type": "boolean"
            },
            "score": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A confidence score for this annotation",
               "title": "Score"
            },
            "data": {
               "additionalProperties": true,
               "description": "\nAn object representation of the annotation including any confidence scores or\ndescriptions.\n",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "value"
         ],
         "title": "BooleanAnnotation",
         "type": "object"
      },
      "DOIIdentifier": {
         "description": "An external identifier representing a DOI.",
         "properties": {
            "identifier": {
               "description": "The DOI of the reference. Format: '10.<registrant>/<suffix>' where registrant is 4-9 digits and suffix is any non-whitespace characters. Examples: 10.1000/journal.pone.0001, 10.18730/9WQ$D, 10.1000/\u00e9dition",
               "pattern": "^10\\.\\d{4,9}/\\S+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "doi",
               "default": "doi",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "DOIIdentifier",
         "type": "object"
      },
      "DriverVersion": {
         "description": "The version based on the DRIVER guidelines versioning scheme.\n\n(Borrowed from OpenAlex)",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "type": "string"
      },
      "DuplicateDetermination": {
         "description": "The determination of whether a reference is a duplicate.\n\nThis encodes both a status and a determination.",
         "enum": [
            "pending",
            "nominated",
            "duplicate",
            "exact_duplicate",
            "canonical",
            "unresolved",
            "unsearchable",
            "decoupled"
         ],
         "title": "DuplicateDetermination",
         "type": "string"
      },
      "ERICIdentifier": {
         "description": "An external identifier representing an ERIC Number.\n\nAn ERIC Number is defined as a unique identifying number preceded by\nED (for a non-journal document) or EJ (for a journal article).",
         "properties": {
            "identifier": {
               "description": "The ERIC Number. Format: 'ED' or 'EJ' followed by digits. Example: ED123456 or EJ789012",
               "pattern": "E[D|J][0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "eric",
               "default": "eric",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ERICIdentifier",
         "type": "object"
      },
      "Enhancement": {
         "description": "Core enhancement model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "created_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp at which the object was created.",
               "title": "Created At"
            },
            "updated_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp at which the object was last updated.",
               "title": "Updated At"
            },
            "source": {
               "description": "The enhancement source for tracking provenance.",
               "title": "Source",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "description": "The level of visibility of the enhancement"
            },
            "robot_version": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version of the robot that generated the content.",
               "title": "Robot Version"
            },
            "derived_from": {
               "anyOf": [
                  {
                     "items": {
                        "format": "uuid",
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of enhancement IDs that this enhancement was derived from.",
               "title": "Derived From"
            },
            "content": {
               "description": "The content of the enhancement.",
               "discriminator": {
                  "mapping": {
                     "abstract": "#/$defs/AbstractContentEnhancement",
                     "annotation": "#/$defs/AnnotationEnhancement",
                     "bibliographic": "#/$defs/BibliographicMetadataEnhancement",
                     "full_text": "#/$defs/FullTextEnhancement",
                     "linked_data": "#/$defs/LinkedDataEnhancement",
                     "location": "#/$defs/LocationEnhancement",
                     "raw": "#/$defs/RawEnhancement",
                     "reference_association": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LinkedDataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/FullTextEnhancement"
                  },
                  {
                     "$ref": "#/$defs/RawEnhancement"
                  }
               ],
               "title": "Content"
            },
            "reference_id": {
               "description": "The ID of the reference this enhancement is associated with.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The reference this enhancement is associated with."
            }
         },
         "required": [
            "source",
            "visibility",
            "content",
            "reference_id"
         ],
         "title": "Enhancement",
         "type": "object"
      },
      "FullTextEnhancement": {
         "description": "An enhancement for storing a link to the full text and its metadata.\n\nWe separate this from the SDK model as it contains a file pointer, not\nthe URL to the file itself.",
         "properties": {
            "enhancement_type": {
               "const": "full_text",
               "default": "full_text",
               "title": "Enhancement Type",
               "type": "string"
            },
            "blob": {
               "$ref": "#/$defs/BlobStorageFile",
               "description": "Blob storage pointer to the full text file."
            },
            "byte_size": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Size of the file in bytes. If provided on import, will be used to validate the file size. Will always be present on enhancements from the repository.",
               "title": "Byte Size"
            },
            "sha256_checksum": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "SHA256 checksum of the file. If provided on import, will be used to verify the integrity of the file. Will always be present on enhancements from the repository.",
               "title": "Sha256 Checksum"
            },
            "mime_type": {
               "default": "application/pdf",
               "description": "The MIME type of the file.",
               "title": "Mime Type",
               "type": "string"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version (according to the DRIVER versioning scheme) of this full text."
            },
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "If this full text is Open Access. May be left as null if this is unknown.",
               "title": "Is Oa"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The publishing license for this full text.",
               "examples": [
                  "apache-2-0",
                  "cc-by",
                  "cc-by-nc",
                  "cc-by-nc-nd",
                  "cc-by-nc-sa",
                  "cc-by-nd",
                  "cc-by-sa",
                  "gpl-v2",
                  "gpl-v3",
                  "isc",
                  "mit",
                  "other-oa",
                  "public-domain"
               ],
               "title": "License"
            },
            "source": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The source from which this full text was obtained.",
               "title": "Source"
            },
            "source_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The URL of the source from which this full text was obtained.",
               "title": "Source Url"
            },
            "retrieved_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp when this full text was retrieved.",
               "title": "Retrieved At"
            }
         },
         "required": [
            "blob"
         ],
         "title": "FullTextEnhancement",
         "type": "object"
      },
      "JsonValue": {},
      "LinkedDataEnhancement": {
         "description": "An enhancement for storing structured data in a linked data format.\n\nThe content is a JSON-LD document conforming to the vocabulary and\ncontext specified. This enhancement type is produced by mapping robots\nthat transform RawEnhancement data into the shared vocabulary.",
         "properties": {
            "enhancement_type": {
               "const": "linked_data",
               "default": "linked_data",
               "title": "Enhancement Type",
               "type": "string"
            },
            "vocabulary_uri": {
               "description": "The URI of the vocabulary against which this data was produced. Used for compatibility checking.",
               "examples": [
                  "https://vocab.evrepo.org/vocabulary/v1"
               ],
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "Vocabulary Uri",
               "type": "string"
            },
            "data": {
               "additionalProperties": {
                  "$ref": "#/$defs/JsonValue"
               },
               "description": "The JSON-LD content. Must contain an '@context' key with a valid URI string. When combined with the @context, this forms a complete linked data graph.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "vocabulary_uri",
            "data"
         ],
         "title": "LinkedDataEnhancement",
         "type": "object"
      },
      "LinkedExternalIdentifier": {
         "description": "External identifier model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "identifier": {
               "description": "The identifier itself.",
               "discriminator": {
                  "mapping": {
                     "doi": "#/$defs/DOIIdentifier",
                     "eric": "#/$defs/ERICIdentifier",
                     "open_alex": "#/$defs/OpenAlexIdentifier",
                     "other": "#/$defs/OtherIdentifier",
                     "pm_id": "#/$defs/PubMedIdentifier",
                     "pro_quest": "#/$defs/ProQuestIdentifier"
                  },
                  "propertyName": "identifier_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/DOIIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ERICIdentifier"
                  },
                  {
                     "$ref": "#/$defs/PubMedIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ProQuestIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OpenAlexIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OtherIdentifier"
                  }
               ],
               "title": "Identifier"
            },
            "reference_id": {
               "description": "The ID of the reference this identifier identifies.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The reference this identifier identifies."
            }
         },
         "required": [
            "identifier",
            "reference_id"
         ],
         "title": "LinkedExternalIdentifier",
         "type": "object"
      },
      "Location": {
         "description": "A location where a reference can be found.\n\nThis maps almost completely to the OpenAlex\n[Location object](https://docs.openalex.org/api-entities/works/work-object/location-object)",
         "properties": {
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): True if an Open Access (OA) version of this work is available\nat this location. May be left as null if this is unknown (and thus)\ntreated effectively as `false`.\n",
               "title": "Is Oa"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\nThe version (according to the DRIVER versioning scheme) of this location.\n"
            },
            "landing_page_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "(From OpenAlex): The landing page URL for this location.",
               "title": "Landing Page Url"
            },
            "pdf_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): A URL where you can find this location as a PDF.\n",
               "title": "Pdf Url"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): The location's publishing license. This can be a Creative\nCommons license such as cc0 or cc-by, a publisher-specific license, or null\nwhich means we are not able to determine a license for this location.\n",
               "title": "License"
            },
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Any extra metadata about this location",
               "title": "Extra"
            }
         },
         "title": "Location",
         "type": "object"
      },
      "LocationEnhancement": {
         "description": "An enhancement which describes locations where this reference can be found.\n\nThis maps closely (almost exactly) to OpenAlex's locations.",
         "properties": {
            "enhancement_type": {
               "const": "location",
               "default": "location",
               "title": "Enhancement Type",
               "type": "string"
            },
            "locations": {
               "description": "A list of locations where this reference can be found.",
               "items": {
                  "$ref": "#/$defs/Location"
               },
               "minItems": 1,
               "title": "Locations",
               "type": "array"
            }
         },
         "required": [
            "locations"
         ],
         "title": "LocationEnhancement",
         "type": "object"
      },
      "OpenAlexIdentifier": {
         "description": "An external identifier representing an OpenAlex ID.",
         "properties": {
            "identifier": {
               "description": "The OpenAlex ID of the reference. Format: 'W' followed by digits. Example: W2741809807",
               "pattern": "^W\\d+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "open_alex",
               "default": "open_alex",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "OpenAlexIdentifier",
         "type": "object"
      },
      "OtherIdentifier": {
         "description": "An external identifier not otherwise defined by the repository.",
         "properties": {
            "identifier": {
               "description": "The identifier of the reference.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "other",
               "default": "other",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            },
            "other_identifier_name": {
               "description": "The name of the undocumented identifier type.",
               "title": "Other Identifier Name",
               "type": "string"
            }
         },
         "required": [
            "identifier",
            "other_identifier_name"
         ],
         "title": "OtherIdentifier",
         "type": "object"
      },
      "Pagination": {
         "description": "Pagination information for journal articles.\n\nMaps to OpenAlex's work.biblio object. All fields are strings to match\nOpenAlex's format, which may include non-numeric values like \"Spring\" or \"A1\".",
         "properties": {
            "volume": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The volume number of the journal/publication.",
               "title": "Volume"
            },
            "issue": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The issue number of the journal/publication.",
               "title": "Issue"
            },
            "first_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The first page number of the reference in the publication.",
               "title": "First Page"
            },
            "last_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The last page number of the reference in the publication.",
               "title": "Last Page"
            }
         },
         "title": "Pagination",
         "type": "object"
      },
      "ProQuestIdentifier": {
         "description": "An external identifier representing a ProQuest ID.",
         "properties": {
            "identifier": {
               "description": "The ProQuest ID of the reference. Format: numeric digits only. Example: 12345678",
               "pattern": "[0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "pro_quest",
               "default": "pro_quest",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ProQuestIdentifier",
         "type": "object"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID (PMID) of the reference. Example: 12345678",
               "exclusiveMinimum": 0,
               "title": "Identifier",
               "type": "integer"
            },
            "identifier_type": {
               "const": "pm_id",
               "default": "pm_id",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "PubMedIdentifier",
         "type": "object"
      },
      "PublicationVenue": {
         "description": "A publication venue (journal, repository, conference, etc.).",
         "properties": {
            "display_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The display name of the venue (journal name, repository name, etc.)",
               "title": "Display Name"
            },
            "venue_type": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenueType"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The type of venue: journal, repository, book, conference, etc."
            },
            "issn": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of ISSNs associated with this venue (print and electronic)",
               "title": "Issn"
            },
            "issn_l": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The linking ISSN - a canonical ISSN for the venue across format changes",
               "title": "Issn L"
            },
            "host_organization_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Display name of the host organization (publisher)",
               "title": "Host Organization Name"
            }
         },
         "title": "PublicationVenue",
         "type": "object"
      },
      "PublicationVenueType": {
         "description": "Type of publication venue.\n\nAligns with OpenAlex source types.",
         "enum": [
            "journal",
            "repository",
            "conference",
            "ebook_platform",
            "book_series",
            "other"
         ],
         "title": "PublicationVenueType",
         "type": "string"
      },
      "RawEnhancement": {
         "description": "An enhancement for storing raw/arbitrary/unstructured data.\n\nData in these enhancements is intended for future conversion into structured form.\n\nThis enhancement accepts any fields passed in to `data`. These enhancements cannot\nbe created by robots.",
         "properties": {
            "enhancement_type": {
               "const": "raw",
               "default": "raw",
               "title": "Enhancement Type",
               "type": "string"
            },
            "source_export_date": {
               "description": "Date the enhancement data was retrieved.",
               "format": "date-time",
               "title": "Source Export Date",
               "type": "string"
            },
            "description": {
               "description": "Description of the data to aid in future refinement.",
               "title": "Description",
               "type": "string"
            },
            "metadata": {
               "additionalProperties": true,
               "description": "Additional metadata to aid in future structuring of raw data",
               "title": "Metadata",
               "type": "object"
            },
            "data": {
               "description": "Unstructured data for later processing.",
               "title": "Data"
            }
         },
         "required": [
            "source_export_date",
            "description",
            "data"
         ],
         "title": "RawEnhancement",
         "type": "object"
      },
      "Reference": {
         "description": "Core reference model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "default": "public",
               "description": "The level of visibility of the reference"
            },
            "identifiers": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/LinkedExternalIdentifier"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `LinkedExternalIdentifiers` for the Reference",
               "title": "Identifiers"
            },
            "enhancements": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Enhancement"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of enhancements for the reference",
               "title": "Enhancements"
            },
            "duplicate_decision": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/ReferenceDuplicateDecision"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The current active duplicate decision for this reference. If None, either duplicate_decision has not been preloaded or the duplicate status is pending."
            },
            "canonical_reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The canonical reference that this reference is a duplicate of"
            },
            "duplicate_references": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Reference"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of references that this reference duplicates",
               "title": "Duplicate References"
            }
         },
         "title": "Reference",
         "type": "object"
      },
      "ReferenceAssociationEnhancement": {
         "description": "An enhancement for storing associations between references.",
         "properties": {
            "enhancement_type": {
               "const": "reference_association",
               "default": "reference_association",
               "title": "Enhancement Type",
               "type": "string"
            },
            "associated_reference_ids": {
               "description": "A list of Identifiers which are associated to this reference. These can either be ExternalIdentifiers or resolved repository UUID4s.",
               "items": {
                  "anyOf": [
                     {
                        "discriminator": {
                           "mapping": {
                              "doi": "#/$defs/DOIIdentifier",
                              "eric": "#/$defs/ERICIdentifier",
                              "open_alex": "#/$defs/OpenAlexIdentifier",
                              "other": "#/$defs/OtherIdentifier",
                              "pm_id": "#/$defs/PubMedIdentifier",
                              "pro_quest": "#/$defs/ProQuestIdentifier"
                           },
                           "propertyName": "identifier_type"
                        },
                        "oneOf": [
                           {
                              "$ref": "#/$defs/DOIIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ERICIdentifier"
                           },
                           {
                              "$ref": "#/$defs/PubMedIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ProQuestIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OpenAlexIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OtherIdentifier"
                           }
                        ]
                     },
                     {
                        "anyOf": [
                           {
                              "format": "uuid4",
                              "type": "string"
                           },
                           {
                              "format": "uuid7",
                              "type": "string"
                           }
                        ],
                        "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
                     }
                  ]
               },
               "minItems": 1,
               "title": "Associated Reference Ids",
               "type": "array"
            },
            "association_type": {
               "$ref": "#/$defs/ReferenceAssociationType",
               "description": "The type of association between this reference and the associated ones. Direction is important: \"this reference <association_type> associated reference\"."
            }
         },
         "required": [
            "associated_reference_ids",
            "association_type"
         ],
         "title": "ReferenceAssociationEnhancement",
         "type": "object"
      },
      "ReferenceAssociationType": {
         "description": "The type of association between references.\n\nDirection is important: \"this reference <association_type> associated reference\".",
         "enum": [
            "cites",
            "is_cited_by",
            "is_similar_to"
         ],
         "title": "ReferenceAssociationType",
         "type": "string"
      },
      "ReferenceDuplicateDecision": {
         "description": "Model representing a decision on whether a reference is a duplicate.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "reference_id": {
               "description": "The ID of the reference being evaluated.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "enhancement_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the enhancement that triggered this duplicate decision, if any.",
               "title": "Enhancement Id"
            },
            "active_decision": {
               "default": false,
               "description": "Whether this is the active decision for the reference.",
               "title": "Active Decision",
               "type": "boolean"
            },
            "candidate_canonical_ids": {
               "description": "A list of candidate canonical IDs for the reference.",
               "items": {
                  "format": "uuid",
                  "type": "string"
               },
               "title": "Candidate Canonical Ids",
               "type": "array"
            },
            "duplicate_determination": {
               "$ref": "#/$defs/DuplicateDetermination",
               "default": "pending",
               "description": "The duplicate status of the reference."
            },
            "canonical_reference_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the canonical reference this reference duplicates.",
               "title": "Canonical Reference Id"
            },
            "detail": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Optional additional detail about the decision.",
               "title": "Detail"
            }
         },
         "required": [
            "reference_id"
         ],
         "title": "ReferenceDuplicateDecision",
         "type": "object"
      },
      "ScoreAnnotation": {
         "description": "An annotation which represents the score for a label.\n\nThis is similar to a BooleanAnnotation, but lacks a boolean determination\nas to the application of the label.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "score": {
               "description": "Score for this annotation",
               "title": "Score",
               "type": "number"
            },
            "data": {
               "additionalProperties": true,
               "description": "An object representation of the annotation including any confidence scores or descriptions.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "score"
         ],
         "title": "ScoreAnnotation",
         "type": "object"
      },
      "Visibility": {
         "description": "The visibility of a data element in the repository.\n\nThis is used to manage whether information should be publicly available or\nrestricted (generally due to copyright constraints from publishers).\n\nTODO: Implement data governance layer to manage this.",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   },
   "required": [
      "total",
      "page"
   ]
}

Fields:

• page (int)

• references (list[app.domain.references.models.models.Reference])

• total (int)

field page: int [Required]

The page number of the results.

field references: list[Reference] [Optional]

The list of references returned from the search query.

field total: int [Required]

The total number of results matching the search query.

pydantic model app.domain.references.models.models.ReferenceWithChangeset

Reference model with a changeset included.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ReferenceWithChangeset",
   "description": "Reference model with a changeset included.",
   "type": "object",
   "properties": {
      "id": {
         "description": "The autogenerated database ID.",
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "visibility": {
         "$ref": "#/$defs/Visibility",
         "default": "public",
         "description": "The level of visibility of the reference"
      },
      "identifiers": {
         "anyOf": [
            {
               "items": {
                  "$ref": "#/$defs/LinkedExternalIdentifier"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "A list of `LinkedExternalIdentifiers` for the Reference",
         "title": "Identifiers"
      },
      "enhancements": {
         "anyOf": [
            {
               "items": {
                  "$ref": "#/$defs/Enhancement"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "A list of enhancements for the reference",
         "title": "Enhancements"
      },
      "duplicate_decision": {
         "anyOf": [
            {
               "$ref": "#/$defs/ReferenceDuplicateDecision"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The current active duplicate decision for this reference. If None, either duplicate_decision has not been preloaded or the duplicate status is pending."
      },
      "canonical_reference": {
         "anyOf": [
            {
               "$ref": "#/$defs/Reference"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The canonical reference that this reference is a duplicate of"
      },
      "duplicate_references": {
         "anyOf": [
            {
               "items": {
                  "$ref": "#/$defs/Reference"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "A list of references that this reference duplicates",
         "title": "Duplicate References"
      },
      "changeset": {
         "$ref": "#/$defs/Reference",
         "description": "The changeset that was applied to the reference. This is purely additive."
      }
   },
   "$defs": {
      "AbstractContentEnhancement": {
         "description": "An enhancement which is specific to the abstract of a reference.\n\nThis is separate from the `BibliographicMetadata` for two reasons:\n\n1. Abstracts are increasingly missing from sources like OpenAlex, and may be\nbackfilled from other sources, without the bibliographic metadata.\n2. They are also subject to copyright limitations in ways which metadata are\nnot, and thus need separate visibility controls.",
         "properties": {
            "enhancement_type": {
               "const": "abstract",
               "default": "abstract",
               "title": "Enhancement Type",
               "type": "string"
            },
            "process": {
               "$ref": "#/$defs/AbstractProcessType"
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquire the abstract.",
         "enum": [
            "uninverted",
            "closed_api",
            "other"
         ],
         "title": "AbstractProcessType",
         "type": "string"
      },
      "AnnotationEnhancement": {
         "description": "An enhancement which is composed of a list of Annotations.",
         "properties": {
            "enhancement_type": {
               "const": "annotation",
               "default": "annotation",
               "title": "Enhancement Type",
               "type": "string"
            },
            "annotations": {
               "items": {
                  "discriminator": {
                     "mapping": {
                        "boolean": "#/$defs/BooleanAnnotation",
                        "score": "#/$defs/ScoreAnnotation"
                     },
                     "propertyName": "annotation_type"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/BooleanAnnotation"
                     },
                     {
                        "$ref": "#/$defs/ScoreAnnotation"
                     }
                  ]
               },
               "minItems": 1,
               "title": "Annotations",
               "type": "array"
            }
         },
         "required": [
            "annotations"
         ],
         "title": "AnnotationEnhancement",
         "type": "object"
      },
      "AuthorPosition": {
         "description": "The position of an author in a list of authorships.\n\nMaps to the data from OpenAlex.",
         "enum": [
            "first",
            "middle",
            "last"
         ],
         "title": "AuthorPosition",
         "type": "string"
      },
      "Authorship": {
         "description": "Represents a single author and their association with a reference.\n\nThis is a simplification of the OpenAlex [Authorship\nobject](https://docs.openalex.org/api-entities/works/work-object/authorship-object)\nfor our purposes.",
         "properties": {
            "display_name": {
               "description": "The display name of the author. Expected format FIRSTNAME <MIDDLENAME> LASTNAME. Providing display_name in an unexpected format will affect search performance.",
               "title": "Display Name",
               "type": "string"
            },
            "orcid": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ORCid of the author.",
               "title": "Orcid"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "position"
         ],
         "title": "Authorship",
         "type": "object"
      },
      "BibliographicMetadataEnhancement": {
         "description": "An enhancement which is made up of bibliographic metadata.\n\nGenerally this will be sourced from a database such as OpenAlex or similar.\nFor directly contributed references, these may not be complete.",
         "properties": {
            "enhancement_type": {
               "const": "bibliographic",
               "default": "bibliographic",
               "title": "Enhancement Type",
               "type": "string"
            },
            "authorship": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Authorship"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `Authorships` belonging to this reference.",
               "title": "Authorship"
            },
            "cited_by_count": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex) The number of citations to this work. These are the times that\nother works have cited this work\n",
               "title": "Cited By Count"
            },
            "created_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date this metadata record was created",
               "title": "Created Date"
            },
            "updated_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date of the last OpenAlex update to this metadata",
               "title": "Updated Date"
            },
            "publication_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The date which the version of record was published.",
               "title": "Publication Date"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The year in which the version of record was published.",
               "title": "Publication Year"
            },
            "publisher": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the entity which published the version of record.",
               "title": "Publisher"
            },
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The title of the reference.",
               "title": "Title"
            },
            "pagination": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Pagination"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Pagination info (volume, issue, pages)."
            },
            "publication_venue": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenue"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Publication venue information (journal, repository, etc.)."
            }
         },
         "title": "BibliographicMetadataEnhancement",
         "type": "object"
      },
      "BlobStorageFile": {
         "description": "Model to represent Blob Storage files.",
         "properties": {
            "location": {
               "$ref": "#/$defs/BlobStorageLocation",
               "description": "The location of the blob storage."
            },
            "container": {
               "description": "The name of the container in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in blob storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio",
            "http",
            "https"
         ],
         "title": "BlobStorageLocation",
         "type": "string"
      },
      "BooleanAnnotation": {
         "description": "An annotation is a way of tagging the content with a label of some kind.\n\nThis class will probably be broken up in the future, but covers most of our\ninitial cases.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "value": {
               "description": "Boolean flag for this annotation",
               "title": "Value",
               "type": "boolean"
            },
            "score": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A confidence score for this annotation",
               "title": "Score"
            },
            "data": {
               "additionalProperties": true,
               "description": "\nAn object representation of the annotation including any confidence scores or\ndescriptions.\n",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "value"
         ],
         "title": "BooleanAnnotation",
         "type": "object"
      },
      "DOIIdentifier": {
         "description": "An external identifier representing a DOI.",
         "properties": {
            "identifier": {
               "description": "The DOI of the reference. Format: '10.<registrant>/<suffix>' where registrant is 4-9 digits and suffix is any non-whitespace characters. Examples: 10.1000/journal.pone.0001, 10.18730/9WQ$D, 10.1000/\u00e9dition",
               "pattern": "^10\\.\\d{4,9}/\\S+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "doi",
               "default": "doi",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "DOIIdentifier",
         "type": "object"
      },
      "DriverVersion": {
         "description": "The version based on the DRIVER guidelines versioning scheme.\n\n(Borrowed from OpenAlex)",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "type": "string"
      },
      "DuplicateDetermination": {
         "description": "The determination of whether a reference is a duplicate.\n\nThis encodes both a status and a determination.",
         "enum": [
            "pending",
            "nominated",
            "duplicate",
            "exact_duplicate",
            "canonical",
            "unresolved",
            "unsearchable",
            "decoupled"
         ],
         "title": "DuplicateDetermination",
         "type": "string"
      },
      "ERICIdentifier": {
         "description": "An external identifier representing an ERIC Number.\n\nAn ERIC Number is defined as a unique identifying number preceded by\nED (for a non-journal document) or EJ (for a journal article).",
         "properties": {
            "identifier": {
               "description": "The ERIC Number. Format: 'ED' or 'EJ' followed by digits. Example: ED123456 or EJ789012",
               "pattern": "E[D|J][0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "eric",
               "default": "eric",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ERICIdentifier",
         "type": "object"
      },
      "Enhancement": {
         "description": "Core enhancement model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "created_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp at which the object was created.",
               "title": "Created At"
            },
            "updated_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp at which the object was last updated.",
               "title": "Updated At"
            },
            "source": {
               "description": "The enhancement source for tracking provenance.",
               "title": "Source",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "description": "The level of visibility of the enhancement"
            },
            "robot_version": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version of the robot that generated the content.",
               "title": "Robot Version"
            },
            "derived_from": {
               "anyOf": [
                  {
                     "items": {
                        "format": "uuid",
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of enhancement IDs that this enhancement was derived from.",
               "title": "Derived From"
            },
            "content": {
               "description": "The content of the enhancement.",
               "discriminator": {
                  "mapping": {
                     "abstract": "#/$defs/AbstractContentEnhancement",
                     "annotation": "#/$defs/AnnotationEnhancement",
                     "bibliographic": "#/$defs/BibliographicMetadataEnhancement",
                     "full_text": "#/$defs/FullTextEnhancement",
                     "linked_data": "#/$defs/LinkedDataEnhancement",
                     "location": "#/$defs/LocationEnhancement",
                     "raw": "#/$defs/RawEnhancement",
                     "reference_association": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LinkedDataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/FullTextEnhancement"
                  },
                  {
                     "$ref": "#/$defs/RawEnhancement"
                  }
               ],
               "title": "Content"
            },
            "reference_id": {
               "description": "The ID of the reference this enhancement is associated with.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The reference this enhancement is associated with."
            }
         },
         "required": [
            "source",
            "visibility",
            "content",
            "reference_id"
         ],
         "title": "Enhancement",
         "type": "object"
      },
      "FullTextEnhancement": {
         "description": "An enhancement for storing a link to the full text and its metadata.\n\nWe separate this from the SDK model as it contains a file pointer, not\nthe URL to the file itself.",
         "properties": {
            "enhancement_type": {
               "const": "full_text",
               "default": "full_text",
               "title": "Enhancement Type",
               "type": "string"
            },
            "blob": {
               "$ref": "#/$defs/BlobStorageFile",
               "description": "Blob storage pointer to the full text file."
            },
            "byte_size": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Size of the file in bytes. If provided on import, will be used to validate the file size. Will always be present on enhancements from the repository.",
               "title": "Byte Size"
            },
            "sha256_checksum": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "SHA256 checksum of the file. If provided on import, will be used to verify the integrity of the file. Will always be present on enhancements from the repository.",
               "title": "Sha256 Checksum"
            },
            "mime_type": {
               "default": "application/pdf",
               "description": "The MIME type of the file.",
               "title": "Mime Type",
               "type": "string"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version (according to the DRIVER versioning scheme) of this full text."
            },
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "If this full text is Open Access. May be left as null if this is unknown.",
               "title": "Is Oa"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The publishing license for this full text.",
               "examples": [
                  "apache-2-0",
                  "cc-by",
                  "cc-by-nc",
                  "cc-by-nc-nd",
                  "cc-by-nc-sa",
                  "cc-by-nd",
                  "cc-by-sa",
                  "gpl-v2",
                  "gpl-v3",
                  "isc",
                  "mit",
                  "other-oa",
                  "public-domain"
               ],
               "title": "License"
            },
            "source": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The source from which this full text was obtained.",
               "title": "Source"
            },
            "source_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The URL of the source from which this full text was obtained.",
               "title": "Source Url"
            },
            "retrieved_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp when this full text was retrieved.",
               "title": "Retrieved At"
            }
         },
         "required": [
            "blob"
         ],
         "title": "FullTextEnhancement",
         "type": "object"
      },
      "JsonValue": {},
      "LinkedDataEnhancement": {
         "description": "An enhancement for storing structured data in a linked data format.\n\nThe content is a JSON-LD document conforming to the vocabulary and\ncontext specified. This enhancement type is produced by mapping robots\nthat transform RawEnhancement data into the shared vocabulary.",
         "properties": {
            "enhancement_type": {
               "const": "linked_data",
               "default": "linked_data",
               "title": "Enhancement Type",
               "type": "string"
            },
            "vocabulary_uri": {
               "description": "The URI of the vocabulary against which this data was produced. Used for compatibility checking.",
               "examples": [
                  "https://vocab.evrepo.org/vocabulary/v1"
               ],
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "Vocabulary Uri",
               "type": "string"
            },
            "data": {
               "additionalProperties": {
                  "$ref": "#/$defs/JsonValue"
               },
               "description": "The JSON-LD content. Must contain an '@context' key with a valid URI string. When combined with the @context, this forms a complete linked data graph.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "vocabulary_uri",
            "data"
         ],
         "title": "LinkedDataEnhancement",
         "type": "object"
      },
      "LinkedExternalIdentifier": {
         "description": "External identifier model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "identifier": {
               "description": "The identifier itself.",
               "discriminator": {
                  "mapping": {
                     "doi": "#/$defs/DOIIdentifier",
                     "eric": "#/$defs/ERICIdentifier",
                     "open_alex": "#/$defs/OpenAlexIdentifier",
                     "other": "#/$defs/OtherIdentifier",
                     "pm_id": "#/$defs/PubMedIdentifier",
                     "pro_quest": "#/$defs/ProQuestIdentifier"
                  },
                  "propertyName": "identifier_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/DOIIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ERICIdentifier"
                  },
                  {
                     "$ref": "#/$defs/PubMedIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ProQuestIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OpenAlexIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OtherIdentifier"
                  }
               ],
               "title": "Identifier"
            },
            "reference_id": {
               "description": "The ID of the reference this identifier identifies.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The reference this identifier identifies."
            }
         },
         "required": [
            "identifier",
            "reference_id"
         ],
         "title": "LinkedExternalIdentifier",
         "type": "object"
      },
      "Location": {
         "description": "A location where a reference can be found.\n\nThis maps almost completely to the OpenAlex\n[Location object](https://docs.openalex.org/api-entities/works/work-object/location-object)",
         "properties": {
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): True if an Open Access (OA) version of this work is available\nat this location. May be left as null if this is unknown (and thus)\ntreated effectively as `false`.\n",
               "title": "Is Oa"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\nThe version (according to the DRIVER versioning scheme) of this location.\n"
            },
            "landing_page_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "(From OpenAlex): The landing page URL for this location.",
               "title": "Landing Page Url"
            },
            "pdf_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): A URL where you can find this location as a PDF.\n",
               "title": "Pdf Url"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): The location's publishing license. This can be a Creative\nCommons license such as cc0 or cc-by, a publisher-specific license, or null\nwhich means we are not able to determine a license for this location.\n",
               "title": "License"
            },
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Any extra metadata about this location",
               "title": "Extra"
            }
         },
         "title": "Location",
         "type": "object"
      },
      "LocationEnhancement": {
         "description": "An enhancement which describes locations where this reference can be found.\n\nThis maps closely (almost exactly) to OpenAlex's locations.",
         "properties": {
            "enhancement_type": {
               "const": "location",
               "default": "location",
               "title": "Enhancement Type",
               "type": "string"
            },
            "locations": {
               "description": "A list of locations where this reference can be found.",
               "items": {
                  "$ref": "#/$defs/Location"
               },
               "minItems": 1,
               "title": "Locations",
               "type": "array"
            }
         },
         "required": [
            "locations"
         ],
         "title": "LocationEnhancement",
         "type": "object"
      },
      "OpenAlexIdentifier": {
         "description": "An external identifier representing an OpenAlex ID.",
         "properties": {
            "identifier": {
               "description": "The OpenAlex ID of the reference. Format: 'W' followed by digits. Example: W2741809807",
               "pattern": "^W\\d+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "open_alex",
               "default": "open_alex",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "OpenAlexIdentifier",
         "type": "object"
      },
      "OtherIdentifier": {
         "description": "An external identifier not otherwise defined by the repository.",
         "properties": {
            "identifier": {
               "description": "The identifier of the reference.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "other",
               "default": "other",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            },
            "other_identifier_name": {
               "description": "The name of the undocumented identifier type.",
               "title": "Other Identifier Name",
               "type": "string"
            }
         },
         "required": [
            "identifier",
            "other_identifier_name"
         ],
         "title": "OtherIdentifier",
         "type": "object"
      },
      "Pagination": {
         "description": "Pagination information for journal articles.\n\nMaps to OpenAlex's work.biblio object. All fields are strings to match\nOpenAlex's format, which may include non-numeric values like \"Spring\" or \"A1\".",
         "properties": {
            "volume": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The volume number of the journal/publication.",
               "title": "Volume"
            },
            "issue": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The issue number of the journal/publication.",
               "title": "Issue"
            },
            "first_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The first page number of the reference in the publication.",
               "title": "First Page"
            },
            "last_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The last page number of the reference in the publication.",
               "title": "Last Page"
            }
         },
         "title": "Pagination",
         "type": "object"
      },
      "ProQuestIdentifier": {
         "description": "An external identifier representing a ProQuest ID.",
         "properties": {
            "identifier": {
               "description": "The ProQuest ID of the reference. Format: numeric digits only. Example: 12345678",
               "pattern": "[0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "pro_quest",
               "default": "pro_quest",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ProQuestIdentifier",
         "type": "object"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID (PMID) of the reference. Example: 12345678",
               "exclusiveMinimum": 0,
               "title": "Identifier",
               "type": "integer"
            },
            "identifier_type": {
               "const": "pm_id",
               "default": "pm_id",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "PubMedIdentifier",
         "type": "object"
      },
      "PublicationVenue": {
         "description": "A publication venue (journal, repository, conference, etc.).",
         "properties": {
            "display_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The display name of the venue (journal name, repository name, etc.)",
               "title": "Display Name"
            },
            "venue_type": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenueType"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The type of venue: journal, repository, book, conference, etc."
            },
            "issn": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of ISSNs associated with this venue (print and electronic)",
               "title": "Issn"
            },
            "issn_l": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The linking ISSN - a canonical ISSN for the venue across format changes",
               "title": "Issn L"
            },
            "host_organization_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Display name of the host organization (publisher)",
               "title": "Host Organization Name"
            }
         },
         "title": "PublicationVenue",
         "type": "object"
      },
      "PublicationVenueType": {
         "description": "Type of publication venue.\n\nAligns with OpenAlex source types.",
         "enum": [
            "journal",
            "repository",
            "conference",
            "ebook_platform",
            "book_series",
            "other"
         ],
         "title": "PublicationVenueType",
         "type": "string"
      },
      "RawEnhancement": {
         "description": "An enhancement for storing raw/arbitrary/unstructured data.\n\nData in these enhancements is intended for future conversion into structured form.\n\nThis enhancement accepts any fields passed in to `data`. These enhancements cannot\nbe created by robots.",
         "properties": {
            "enhancement_type": {
               "const": "raw",
               "default": "raw",
               "title": "Enhancement Type",
               "type": "string"
            },
            "source_export_date": {
               "description": "Date the enhancement data was retrieved.",
               "format": "date-time",
               "title": "Source Export Date",
               "type": "string"
            },
            "description": {
               "description": "Description of the data to aid in future refinement.",
               "title": "Description",
               "type": "string"
            },
            "metadata": {
               "additionalProperties": true,
               "description": "Additional metadata to aid in future structuring of raw data",
               "title": "Metadata",
               "type": "object"
            },
            "data": {
               "description": "Unstructured data for later processing.",
               "title": "Data"
            }
         },
         "required": [
            "source_export_date",
            "description",
            "data"
         ],
         "title": "RawEnhancement",
         "type": "object"
      },
      "Reference": {
         "description": "Core reference model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "default": "public",
               "description": "The level of visibility of the reference"
            },
            "identifiers": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/LinkedExternalIdentifier"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `LinkedExternalIdentifiers` for the Reference",
               "title": "Identifiers"
            },
            "enhancements": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Enhancement"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of enhancements for the reference",
               "title": "Enhancements"
            },
            "duplicate_decision": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/ReferenceDuplicateDecision"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The current active duplicate decision for this reference. If None, either duplicate_decision has not been preloaded or the duplicate status is pending."
            },
            "canonical_reference": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Reference"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The canonical reference that this reference is a duplicate of"
            },
            "duplicate_references": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Reference"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of references that this reference duplicates",
               "title": "Duplicate References"
            }
         },
         "title": "Reference",
         "type": "object"
      },
      "ReferenceAssociationEnhancement": {
         "description": "An enhancement for storing associations between references.",
         "properties": {
            "enhancement_type": {
               "const": "reference_association",
               "default": "reference_association",
               "title": "Enhancement Type",
               "type": "string"
            },
            "associated_reference_ids": {
               "description": "A list of Identifiers which are associated to this reference. These can either be ExternalIdentifiers or resolved repository UUID4s.",
               "items": {
                  "anyOf": [
                     {
                        "discriminator": {
                           "mapping": {
                              "doi": "#/$defs/DOIIdentifier",
                              "eric": "#/$defs/ERICIdentifier",
                              "open_alex": "#/$defs/OpenAlexIdentifier",
                              "other": "#/$defs/OtherIdentifier",
                              "pm_id": "#/$defs/PubMedIdentifier",
                              "pro_quest": "#/$defs/ProQuestIdentifier"
                           },
                           "propertyName": "identifier_type"
                        },
                        "oneOf": [
                           {
                              "$ref": "#/$defs/DOIIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ERICIdentifier"
                           },
                           {
                              "$ref": "#/$defs/PubMedIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ProQuestIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OpenAlexIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OtherIdentifier"
                           }
                        ]
                     },
                     {
                        "anyOf": [
                           {
                              "format": "uuid4",
                              "type": "string"
                           },
                           {
                              "format": "uuid7",
                              "type": "string"
                           }
                        ],
                        "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
                     }
                  ]
               },
               "minItems": 1,
               "title": "Associated Reference Ids",
               "type": "array"
            },
            "association_type": {
               "$ref": "#/$defs/ReferenceAssociationType",
               "description": "The type of association between this reference and the associated ones. Direction is important: \"this reference <association_type> associated reference\"."
            }
         },
         "required": [
            "associated_reference_ids",
            "association_type"
         ],
         "title": "ReferenceAssociationEnhancement",
         "type": "object"
      },
      "ReferenceAssociationType": {
         "description": "The type of association between references.\n\nDirection is important: \"this reference <association_type> associated reference\".",
         "enum": [
            "cites",
            "is_cited_by",
            "is_similar_to"
         ],
         "title": "ReferenceAssociationType",
         "type": "string"
      },
      "ReferenceDuplicateDecision": {
         "description": "Model representing a decision on whether a reference is a duplicate.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "reference_id": {
               "description": "The ID of the reference being evaluated.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "enhancement_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the enhancement that triggered this duplicate decision, if any.",
               "title": "Enhancement Id"
            },
            "active_decision": {
               "default": false,
               "description": "Whether this is the active decision for the reference.",
               "title": "Active Decision",
               "type": "boolean"
            },
            "candidate_canonical_ids": {
               "description": "A list of candidate canonical IDs for the reference.",
               "items": {
                  "format": "uuid",
                  "type": "string"
               },
               "title": "Candidate Canonical Ids",
               "type": "array"
            },
            "duplicate_determination": {
               "$ref": "#/$defs/DuplicateDetermination",
               "default": "pending",
               "description": "The duplicate status of the reference."
            },
            "canonical_reference_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the canonical reference this reference duplicates.",
               "title": "Canonical Reference Id"
            },
            "detail": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Optional additional detail about the decision.",
               "title": "Detail"
            }
         },
         "required": [
            "reference_id"
         ],
         "title": "ReferenceDuplicateDecision",
         "type": "object"
      },
      "ScoreAnnotation": {
         "description": "An annotation which represents the score for a label.\n\nThis is similar to a BooleanAnnotation, but lacks a boolean determination\nas to the application of the label.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "score": {
               "description": "Score for this annotation",
               "title": "Score",
               "type": "number"
            },
            "data": {
               "additionalProperties": true,
               "description": "An object representation of the annotation including any confidence scores or descriptions.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "score"
         ],
         "title": "ScoreAnnotation",
         "type": "object"
      },
      "Visibility": {
         "description": "The visibility of a data element in the repository.\n\nThis is used to manage whether information should be publicly available or\nrestricted (generally due to copyright constraints from publishers).\n\nTODO: Implement data governance layer to manage this.",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   },
   "required": [
      "changeset"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• canonical_reference ()

• changeset (app.domain.references.models.models.Reference)

• duplicate_decision ()

• duplicate_references ()

• enhancements ()

• id ()

• identifiers ()

• visibility ()

field canonical_reference: Reference | None = None

The canonical reference that this reference is a duplicate of

field changeset: Reference [Required]

The changeset that was applied to the reference. This is purely additive.

field duplicate_decision: ReferenceDuplicateDecision | None = None

The current active duplicate decision for this reference. If None, either duplicate_decision has not been preloaded or the duplicate status is pending.

field duplicate_references: list['Reference'] | None = None

A list of references that this reference duplicates

field enhancements: list['Enhancement'] | None = None

A list of enhancements for the reference

field id: UUID [Optional]

The autogenerated database ID.

field identifiers: list['LinkedExternalIdentifier'] | None = None

A list of LinkedExternalIdentifiers for the Reference

field visibility: Visibility = Visibility.PUBLIC

The level of visibility of the reference

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

is_superset(reference: Reference) → bool

Check if this Reference is a superset of the given Reference.

This compares enhancements, identifiers and visibility, removing persistence differences (eg database ids), to verify if the content is identical. If the given Reference has anything unique, this will return False.

Parameters:

reference (Reference) – The reference to compare against.

Returns:

True if the given Reference is a subset of this Reference, else False.

Return type:

bool

property has_duplicates: bool | None

Whether this reference has any duplicate references pointing to it.

Will return None if duplicate references are not preloaded.

property is_canonical: bool | None

Pessimistically check if this reference is the canonical version.

Returns None if no duplicate decision is present, either due to not being preloaded or still pending.

property is_canonical_like: bool

Optimistically check if this reference is the canonical version.

Only returns False if the reference is a determined duplicate. Pending, unresolved and not-preloaded duplicate decisions are treated as canonical-like.

class app.domain.references.models.models.RetrievalPolicyName(*values)

Named, versioned candidate-retrieval policies for the Candidate Selection API.

Each value fixes a full retrieval regime (query shape, year strategy, identifier union) under a stable name so recall@K stays comparable across runs. A name’s semantics never change; a new regime gets a new name.

CURRENT_FUZZY_V1 = 'current_fuzzy_v1'

Control: fuzzy title/author match with a hard +/-1 publication-year window; requires publication year as input. Mirrors the baseline gate.

NO_YEAR_FILTER_V1 = 'no_year_filter_v1'

Drops the year filter from the query, but still requires publication year as input.

NO_YEAR_FILTER_YEAR_OPTIONAL_V1 = 'no_year_filter_year_optional_v1'

Drops the year filter and makes publication year optional as input.

SOFT_YEAR_DECAY_NONFUZZY_PROBE_V1 = 'soft_year_decay_nonfuzzy_probe_v1'

Evaluation-only probe: soft_year_decay_v1 with zero edit-distance title matching. Used to measure the recall and latency impact of disabling fuzzy title matching for this query shape. Not for production nomination.

SOFT_YEAR_DECAY_V1 = 'soft_year_decay_v1'

Bounded soft year decay: no hard year filter; a native Elasticsearch exponential proximity bonus adds at most 10% to the title/author score. Requires publication year as input.

pydantic model app.domain.references.models.models.RobotAutomation

Automation model for a robot.

This is used as a source of truth for an Elasticsearch index that percolates references or enhancements against the queries. If a query matches, a request is sent to the specified robot to perform the enhancement.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "RobotAutomation",
   "description": "Automation model for a robot.\n\nThis is used as a source of truth for an Elasticsearch index that percolates\nreferences or enhancements against the queries. If a query matches, a request\nis sent to the specified robot to perform the enhancement.",
   "type": "object",
   "properties": {
      "id": {
         "description": "The autogenerated database ID.",
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "robot_id": {
         "description": "The ID of the robot that will be used to enhance the reference.",
         "format": "uuid",
         "title": "Robot Id",
         "type": "string"
      },
      "query": {
         "additionalProperties": true,
         "description": "The query that will be used to match references against.",
         "title": "Query",
         "type": "object"
      }
   },
   "required": [
      "robot_id",
      "query"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• id (uuid.UUID)

• query (dict[str, Any])

• robot_id (uuid.UUID)

field id: UUID [Optional]

The autogenerated database ID.

field query: dict[str, Any] [Required]

The query that will be used to match references against.

field robot_id: UUID [Required]

The ID of the robot that will be used to enhance the reference.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

pydantic model app.domain.references.models.models.RobotAutomationPercolationResult

Result of a percolation query against RobotAutomations.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "RobotAutomationPercolationResult",
   "description": "Result of a percolation query against RobotAutomations.",
   "type": "object",
   "properties": {
      "robot_id": {
         "format": "uuid",
         "title": "Robot Id",
         "type": "string"
      },
      "reference_ids": {
         "items": {
            "format": "uuid",
            "type": "string"
         },
         "title": "Reference Ids",
         "type": "array",
         "uniqueItems": true
      }
   },
   "required": [
      "robot_id",
      "reference_ids"
   ]
}

Fields:

• reference_ids (set[uuid.UUID])

• robot_id (uuid.UUID)

field reference_ids: set[UUID] [Required]

field robot_id: UUID [Required]

pydantic model app.domain.references.models.models.RobotEnhancementBatch

A batch of references to be enhanced by a robot.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "RobotEnhancementBatch",
   "description": "A batch of references to be enhanced by a robot.",
   "type": "object",
   "properties": {
      "id": {
         "description": "The autogenerated database ID.",
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "robot_id": {
         "description": "The ID of the robot that will perform the enhancement.",
         "format": "uuid",
         "title": "Robot Id",
         "type": "string"
      },
      "reference_data_file": {
         "anyOf": [
            {
               "$ref": "#/$defs/BlobStorageFile"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The file containing the references to be enhanced."
      },
      "result_file": {
         "anyOf": [
            {
               "$ref": "#/$defs/BlobStorageFile"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The file containing the enhancement results."
      },
      "validation_result_file": {
         "anyOf": [
            {
               "$ref": "#/$defs/BlobStorageFile"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The file containing validation result data from the repository."
      },
      "error": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Error encountered during the enhancement batch process.",
         "title": "Error"
      },
      "pending_enhancements": {
         "anyOf": [
            {
               "items": {
                  "$ref": "#/$defs/PendingEnhancement"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The pending enhancements in this batch.",
         "title": "Pending Enhancements"
      }
   },
   "$defs": {
      "BlobStorageFile": {
         "description": "Model to represent Blob Storage files.",
         "properties": {
            "location": {
               "$ref": "#/$defs/BlobStorageLocation",
               "description": "The location of the blob storage."
            },
            "container": {
               "description": "The name of the container in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in blob storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio",
            "http",
            "https"
         ],
         "title": "BlobStorageLocation",
         "type": "string"
      },
      "PendingEnhancement": {
         "description": "A pending enhancement.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "reference_id": {
               "description": "The ID of the reference to be enhanced.",
               "format": "uuid",
               "title": "Reference Id",
               "type": "string"
            },
            "robot_id": {
               "description": "The ID of the robot that will perform the enhancement.",
               "format": "uuid",
               "title": "Robot Id",
               "type": "string"
            },
            "enhancement_request_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the batch enhancement request that this pending enhancement belongs to.",
               "title": "Enhancement Request Id"
            },
            "robot_enhancement_batch_id": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the robot enhancement batch that this pending enhancement belongs to.",
               "title": "Robot Enhancement Batch Id"
            },
            "status": {
               "$ref": "#/$defs/PendingEnhancementStatus",
               "default": "pending",
               "description": "The status of the pending enhancement."
            },
            "source": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The source of the pending enhancement for provenance tracking, if not an enhancement request.",
               "title": "Source"
            },
            "expires_at": {
               "default": "1970-01-01T00:00:00Z",
               "description": "The datetime at which the pending enhancement expires.",
               "format": "date-time",
               "title": "Expires At",
               "type": "string"
            },
            "retry_of": {
               "anyOf": [
                  {
                     "format": "uuid",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the pending enhancement that this is a retry of, if any.",
               "title": "Retry Of"
            }
         },
         "required": [
            "reference_id",
            "robot_id"
         ],
         "title": "PendingEnhancement",
         "type": "object"
      },
      "PendingEnhancementStatus": {
         "description": "The status of a pending enhancement.\n\n**Allowed values**:\n- `pending`: Enhancement is waiting to be processed.\n- `processing`: Enhancement is currently being processed.\n- `importing`: Enhancement is currently being imported.\n- `indexing`: Enhancement is currently being indexed.\n- `indexing_failed`: Enhancement indexing has failed.\n- `discarded`: Enhancement has been discarded as an exact duplicate.\n- `completed`: Enhancement has been processed successfully.\n- `failed`: Enhancement processing has failed.\n- `expired`: Enhancement lease has expired during processing.",
         "enum": [
            "pending",
            "processing",
            "importing",
            "indexing",
            "indexing_failed",
            "discarded",
            "completed",
            "failed",
            "expired"
         ],
         "title": "PendingEnhancementStatus",
         "type": "string"
      }
   },
   "required": [
      "robot_id"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• error (str | None)

• id (uuid.UUID)

• pending_enhancements (list[app.domain.references.models.models.PendingEnhancement] | None)

• reference_data_file (app.persistence.blob.models.BlobStorageFile | None)

• result_file (app.persistence.blob.models.BlobStorageFile | None)

• robot_id (uuid.UUID)

• validation_result_file (app.persistence.blob.models.BlobStorageFile | None)

field error: str | None = None

Error encountered during the enhancement batch process.

field id: UUID [Optional]

The autogenerated database ID.

field pending_enhancements: list[PendingEnhancement] | None = None

The pending enhancements in this batch.

field reference_data_file: BlobStorageFile | None = None

The file containing the references to be enhanced.

field result_file: BlobStorageFile | None = None

The file containing the enhancement results.

field robot_id: UUID [Required]

The ID of the robot that will perform the enhancement.

field validation_result_file: BlobStorageFile | None = None

The file containing validation result data from the repository.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

pydantic model app.domain.references.models.models.RobotResultValidationEntry

A single entry in the validation result file for a enhancement request.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "RobotResultValidationEntry",
   "description": "A single entry in the validation result file for a enhancement request.",
   "type": "object",
   "properties": {
      "reference_id": {
         "anyOf": [
            {
               "format": "uuid",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The ID of the reference which was enhanced. If this is empty, the EnhancementResultEntry could not be parsed.",
         "title": "Reference Id"
      },
      "error": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Error encountered during the enhancement process for this reference. If this is empty, the enhancement was successfully created.",
         "title": "Error"
      }
   }
}

Fields:

• error (str | None)

• reference_id (uuid.UUID | None)

field error: str | None = None

Error encountered during the enhancement process for this reference. If this is empty, the enhancement was successfully created.

field reference_id: UUID | None = None

The ID of the reference which was enhanced. If this is empty, the EnhancementResultEntry could not be parsed.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

pydantic model app.domain.references.models.models.SearchExport

A queued job that produces a file of references matching a search.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "SearchExport",
   "description": "A queued job that produces a file of references matching a search.",
   "type": "object",
   "properties": {
      "id": {
         "description": "The autogenerated database ID.",
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "export_format": {
         "$ref": "#/$defs/ExportFormat",
         "default": "jsonl",
         "description": "The serialization format of the produced file."
      },
      "status": {
         "$ref": "#/$defs/ExportStatus",
         "default": "pending",
         "description": "The current status of the export job."
      },
      "result_file": {
         "anyOf": [
            {
               "$ref": "#/$defs/BlobStorageFile"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The file produced by the job, once completed."
      },
      "n_references": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The number of references in the produced file.",
         "title": "N References"
      },
      "error": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Error message, if the job failed.",
         "title": "Error"
      },
      "query": {
         "$ref": "#/$defs/SearchQuery",
         "description": "The search specification this export resolves."
      },
      "sort": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Sort fields, in the same form `/references/search/` accepts.",
         "title": "Sort"
      },
      "truncated": {
         "default": false,
         "description": "Whether the matching result set was larger than the server's result-window cap. When true, the JSONL contains only the first window's worth of matches.",
         "title": "Truncated",
         "type": "boolean"
      }
   },
   "$defs": {
      "AnnotationFilter": {
         "description": "Model representing an annotation filter for searching references.",
         "properties": {
            "scheme": {
               "description": "The annotation scheme to filter on.",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The annotation label to filter on.",
               "title": "Label"
            },
            "score": {
               "anyOf": [
                  {
                     "maximum": 1.0,
                     "minimum": 0.0,
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Optional score threshold for the annotation filter.",
               "title": "Score"
            }
         },
         "required": [
            "scheme"
         ],
         "title": "AnnotationFilter",
         "type": "object"
      },
      "BlobStorageFile": {
         "description": "Model to represent Blob Storage files.",
         "properties": {
            "location": {
               "$ref": "#/$defs/BlobStorageLocation",
               "description": "The location of the blob storage."
            },
            "container": {
               "description": "The name of the container in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in blob storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in blob storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio",
            "http",
            "https"
         ],
         "title": "BlobStorageLocation",
         "type": "string"
      },
      "ExportFormat": {
         "description": "The serialization format of a reference export.",
         "enum": [
            "jsonl",
            "ris"
         ],
         "title": "ExportFormat",
         "type": "string"
      },
      "ExportStatus": {
         "description": "The status of an export job.",
         "enum": [
            "pending",
            "running",
            "completed",
            "failed"
         ],
         "title": "ExportStatus",
         "type": "string"
      },
      "LinkedDataConceptFilter": {
         "description": "A set of fully-qualified concept URIs to match on ``linked_data_concepts``.\n\nWithin a single filter, references must carry at least one of the listed URIs\n(logical OR). Multiple filters on a query are ANDed together.",
         "properties": {
            "concept_uris": {
               "description": "Concept URIs to match. At least one must appear on the reference.",
               "items": {
                  "type": "string"
               },
               "minItems": 1,
               "title": "Concept Uris",
               "type": "array"
            }
         },
         "required": [
            "concept_uris"
         ],
         "title": "LinkedDataConceptFilter",
         "type": "object"
      },
      "LinkedDataCountryFilter": {
         "description": "A set of ISO 3166-1 alpha-2 codes to match on ``linked_data_countries``.\n\nOR within a filter; AND between filters.",
         "properties": {
            "country_codes": {
               "description": "ISO 3166-1 alpha-2 country codes. At least one must appear on the reference.",
               "items": {
                  "pattern": "^[A-Z]{2}$",
                  "type": "string"
               },
               "minItems": 1,
               "title": "Country Codes",
               "type": "array"
            }
         },
         "required": [
            "country_codes"
         ],
         "title": "LinkedDataCountryFilter",
         "type": "object"
      },
      "LinkedDataCountryWBRegionFilter": {
         "description": "A set of World Bank region IDs to match on ``linked_data_country_wb_regions``.\n\nOR within a filter; AND between filters.",
         "properties": {
            "region_ids": {
               "description": "World Bank region IDs. At least one must appear on the reference.",
               "items": {
                  "enum": [
                     "EAS",
                     "ECS",
                     "LCN",
                     "MEA",
                     "NAC",
                     "SAS",
                     "SSF"
                  ],
                  "type": "string"
               },
               "minItems": 1,
               "title": "Region Ids",
               "type": "array"
            }
         },
         "required": [
            "region_ids"
         ],
         "title": "LinkedDataCountryWBRegionFilter",
         "type": "object"
      },
      "PublicationYearRange": {
         "description": "A range of publication years for filtering search results.",
         "properties": {
            "start": {
               "anyOf": [
                  {
                     "exclusiveMinimum": 0,
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Start year (inclusive)",
               "title": "Start"
            },
            "end": {
               "anyOf": [
                  {
                     "exclusiveMinimum": 0,
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "End year (inclusive)",
               "title": "End"
            }
         },
         "title": "PublicationYearRange",
         "type": "object"
      },
      "SearchQuery": {
         "description": "A specification for searching references.",
         "properties": {
            "query_string": {
               "description": "The Lucene query string to search with.",
               "title": "Query String",
               "type": "string"
            },
            "annotation_filters": {
               "description": "Annotation filters to AND with the query string.",
               "items": {
                  "$ref": "#/$defs/AnnotationFilter"
               },
               "title": "Annotation Filters",
               "type": "array"
            },
            "publication_year_range": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationYearRange"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Publication year range to AND with the query string."
            },
            "linked_data_concept_filters": {
               "description": "Concept URI filters to AND with the query string. Each filter is an OR-set of URIs.",
               "items": {
                  "$ref": "#/$defs/LinkedDataConceptFilter"
               },
               "title": "Linked Data Concept Filters",
               "type": "array"
            },
            "linked_data_country_filters": {
               "description": "Country code filters to AND with the query string. Each filter is an OR-set of ISO 3166-1 alpha-2 codes.",
               "items": {
                  "$ref": "#/$defs/LinkedDataCountryFilter"
               },
               "title": "Linked Data Country Filters",
               "type": "array"
            },
            "linked_data_country_wb_region_filters": {
               "description": "World Bank region filters to AND with the query string. Each filter is an OR-set of region IDs.",
               "items": {
                  "$ref": "#/$defs/LinkedDataCountryWBRegionFilter"
               },
               "title": "Linked Data Country Wb Region Filters",
               "type": "array"
            }
         },
         "required": [
            "query_string"
         ],
         "title": "SearchQuery",
         "type": "object"
      }
   },
   "required": [
      "query"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• error ()

• export_format ()

• id ()

• n_references ()

• query (SearchQuery)

• result_file ()

• sort (list[str] | None)

• status ()

• truncated (bool)

field error: str | None = None

Error message, if the job failed.

field export_format: ExportFormat = ExportFormat.JSONL

The serialization format of the produced file.

field id: UUID [Optional]

The autogenerated database ID.

field n_references: int | None = None

The number of references in the produced file.

field query: SearchQuery [Required]

The search specification this export resolves.

field result_file: BlobStorageFile | None = None

The file produced by the job, once completed.

field sort: list[str] | None = None

Sort fields, in the same form /references/search/ accepts.

field status: ExportStatus = ExportStatus.PENDING

The current status of the export job.

field truncated: bool = False

Whether the matching result set was larger than the server’s result-window cap. When true, the JSONL contains only the first window’s worth of matches.

check_serializability() → None

Check that incoming SDK model is json-serializable.

This should be called during all domain model conversions.

Raises:

ValidationError: If the model is not json-serializable.

app.domain.references.models.models.SearchExportStatus

alias of ExportStatus

pydantic model app.domain.references.models.models.SearchQuery

A specification for searching references.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "SearchQuery",
   "description": "A specification for searching references.",
   "type": "object",
   "properties": {
      "query_string": {
         "description": "The Lucene query string to search with.",
         "title": "Query String",
         "type": "string"
      },
      "annotation_filters": {
         "description": "Annotation filters to AND with the query string.",
         "items": {
            "$ref": "#/$defs/AnnotationFilter"
         },
         "title": "Annotation Filters",
         "type": "array"
      },
      "publication_year_range": {
         "anyOf": [
            {
               "$ref": "#/$defs/PublicationYearRange"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Publication year range to AND with the query string."
      },
      "linked_data_concept_filters": {
         "description": "Concept URI filters to AND with the query string. Each filter is an OR-set of URIs.",
         "items": {
            "$ref": "#/$defs/LinkedDataConceptFilter"
         },
         "title": "Linked Data Concept Filters",
         "type": "array"
      },
      "linked_data_country_filters": {
         "description": "Country code filters to AND with the query string. Each filter is an OR-set of ISO 3166-1 alpha-2 codes.",
         "items": {
            "$ref": "#/$defs/LinkedDataCountryFilter"
         },
         "title": "Linked Data Country Filters",
         "type": "array"
      },
      "linked_data_country_wb_region_filters": {
         "description": "World Bank region filters to AND with the query string. Each filter is an OR-set of region IDs.",
         "items": {
            "$ref": "#/$defs/LinkedDataCountryWBRegionFilter"
         },
         "title": "Linked Data Country Wb Region Filters",
         "type": "array"
      }
   },
   "$defs": {
      "AnnotationFilter": {
         "description": "Model representing an annotation filter for searching references.",
         "properties": {
            "scheme": {
               "description": "The annotation scheme to filter on.",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The annotation label to filter on.",
               "title": "Label"
            },
            "score": {
               "anyOf": [
                  {
                     "maximum": 1.0,
                     "minimum": 0.0,
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Optional score threshold for the annotation filter.",
               "title": "Score"
            }
         },
         "required": [
            "scheme"
         ],
         "title": "AnnotationFilter",
         "type": "object"
      },
      "LinkedDataConceptFilter": {
         "description": "A set of fully-qualified concept URIs to match on ``linked_data_concepts``.\n\nWithin a single filter, references must carry at least one of the listed URIs\n(logical OR). Multiple filters on a query are ANDed together.",
         "properties": {
            "concept_uris": {
               "description": "Concept URIs to match. At least one must appear on the reference.",
               "items": {
                  "type": "string"
               },
               "minItems": 1,
               "title": "Concept Uris",
               "type": "array"
            }
         },
         "required": [
            "concept_uris"
         ],
         "title": "LinkedDataConceptFilter",
         "type": "object"
      },
      "LinkedDataCountryFilter": {
         "description": "A set of ISO 3166-1 alpha-2 codes to match on ``linked_data_countries``.\n\nOR within a filter; AND between filters.",
         "properties": {
            "country_codes": {
               "description": "ISO 3166-1 alpha-2 country codes. At least one must appear on the reference.",
               "items": {
                  "pattern": "^[A-Z]{2}$",
                  "type": "string"
               },
               "minItems": 1,
               "title": "Country Codes",
               "type": "array"
            }
         },
         "required": [
            "country_codes"
         ],
         "title": "LinkedDataCountryFilter",
         "type": "object"
      },
      "LinkedDataCountryWBRegionFilter": {
         "description": "A set of World Bank region IDs to match on ``linked_data_country_wb_regions``.\n\nOR within a filter; AND between filters.",
         "properties": {
            "region_ids": {
               "description": "World Bank region IDs. At least one must appear on the reference.",
               "items": {
                  "enum": [
                     "EAS",
                     "ECS",
                     "LCN",
                     "MEA",
                     "NAC",
                     "SAS",
                     "SSF"
                  ],
                  "type": "string"
               },
               "minItems": 1,
               "title": "Region Ids",
               "type": "array"
            }
         },
         "required": [
            "region_ids"
         ],
         "title": "LinkedDataCountryWBRegionFilter",
         "type": "object"
      },
      "PublicationYearRange": {
         "description": "A range of publication years for filtering search results.",
         "properties": {
            "start": {
               "anyOf": [
                  {
                     "exclusiveMinimum": 0,
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Start year (inclusive)",
               "title": "Start"
            },
            "end": {
               "anyOf": [
                  {
                     "exclusiveMinimum": 0,
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "End year (inclusive)",
               "title": "End"
            }
         },
         "title": "PublicationYearRange",
         "type": "object"
      }
   },
   "required": [
      "query_string"
   ]
}

Fields:

• annotation_filters (list[app.domain.references.models.models.AnnotationFilter])

• linked_data_concept_filters (list[app.domain.references.models.models.LinkedDataConceptFilter])

• linked_data_country_filters (list[app.domain.references.models.models.LinkedDataCountryFilter])

• linked_data_country_wb_region_filters (list[app.domain.references.models.models.LinkedDataCountryWBRegionFilter])

• publication_year_range (app.domain.references.models.models.PublicationYearRange | None)

• query_string (str)

field annotation_filters: list[AnnotationFilter] [Optional]

Annotation filters to AND with the query string.

field linked_data_concept_filters: list[LinkedDataConceptFilter] [Optional]

Concept URI filters to AND with the query string. Each filter is an OR-set of URIs.

field linked_data_country_filters: list[LinkedDataCountryFilter] [Optional]

Country code filters to AND with the query string. Each filter is an OR-set of ISO 3166-1 alpha-2 codes.

field linked_data_country_wb_region_filters: list[LinkedDataCountryWBRegionFilter] [Optional]

World Bank region filters to AND with the query string. Each filter is an OR-set of region IDs.

field publication_year_range: PublicationYearRange | None = None

Publication year range to AND with the query string.

field query_string: str [Required]

The Lucene query string to search with.

pydantic model app.domain.references.models.models.SiblingGroup

A user-selected subset of a sibling set, for sibling-aware facet aggregation.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "SiblingGroup",
   "description": "A user-selected subset of a sibling set, for sibling-aware facet aggregation.",
   "type": "object",
   "properties": {
      "selected": {
         "description": "Values the user selected from this sibling set.",
         "items": {
            "type": "string"
         },
         "title": "Selected",
         "type": "array"
      },
      "siblings_including_selected": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array",
               "uniqueItems": true
            },
            {
               "type": "null"
            }
         ],
         "description": "Union of the user's selection and their siblings, used as the ``include`` set for the group's facet aggregation. ``None`` signals universal mode: every value of the field is treated as a sibling, so the agg uses no ``include`` filter.",
         "title": "Siblings Including Selected"
      }
   },
   "required": [
      "selected",
      "siblings_including_selected"
   ]
}

Config:

• frozen: bool = True

Fields:

• selected (tuple[str, ...])

• siblings_including_selected (frozenset[str] | None)

field selected: tuple[str, ...] [Required]

Values the user selected from this sibling set.

field siblings_including_selected: frozenset[str] | None [Required]

Union of the user’s selection and their siblings, used as the include set for the group’s facet aggregation. None signals universal mode: every value of the field is treated as a sibling, so the agg uses no include filter.

class app.domain.references.models.models.Visibility(*values)

The visibility of a data element in the repository.

This is used to manage whether information should be publicly available or restricted (generally due to copyright constraints from publishers).

TODO: Implement data governance layer to manage this.

HIDDEN = 'hidden'

Is not visible, but may be passed to data mining processes.

PUBLIC = 'public'

Visible to the general public without authentication.

RESTRICTED = 'restricted'

Requires authentication to be visible.

pydantic model app.domain.references.models.models.YearDecay

Resolved decay spec carried on a candidate query; origin is required.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "YearDecay",
   "description": "Resolved decay spec carried on a candidate query; origin is required.",
   "type": "object",
   "properties": {
      "offset": {
         "default": 1,
         "minimum": 0,
         "title": "Offset",
         "type": "integer"
      },
      "scale": {
         "default": 9,
         "exclusiveMinimum": 0,
         "title": "Scale",
         "type": "integer"
      },
      "decay": {
         "default": 0.5,
         "exclusiveMaximum": 1,
         "exclusiveMinimum": 0,
         "title": "Decay",
         "type": "number"
      },
      "weight": {
         "default": 0.1,
         "minimum": 0,
         "title": "Weight",
         "type": "number"
      },
      "origin": {
         "title": "Origin",
         "type": "integer"
      }
   },
   "required": [
      "origin"
   ]
}

Config:

• frozen: bool = True

Fields:

• decay (float)

• offset (int)

• origin (int)

• scale (int)

• weight (float)

field decay: float = 0.5

Constraints:

• gt = 0

• lt = 1

field offset: int = 1

Constraints:

• ge = 0

field origin: int [Required]

field scale: int = 9

Constraints:

• gt = 0

field weight: float = 0.1

Constraints:

• ge = 0

property max_boost: float

Cap on the summed function score; stays pinned to the bonus weight.

pydantic model app.domain.references.models.models.YearDecayConfig

Immutable, versioned publication-year decay parameters (no query origin).

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "YearDecayConfig",
   "description": "Immutable, versioned publication-year decay parameters (no query origin).",
   "type": "object",
   "properties": {
      "offset": {
         "default": 1,
         "minimum": 0,
         "title": "Offset",
         "type": "integer"
      },
      "scale": {
         "default": 9,
         "exclusiveMinimum": 0,
         "title": "Scale",
         "type": "integer"
      },
      "decay": {
         "default": 0.5,
         "exclusiveMaximum": 1,
         "exclusiveMinimum": 0,
         "title": "Decay",
         "type": "number"
      },
      "weight": {
         "default": 0.1,
         "minimum": 0,
         "title": "Weight",
         "type": "number"
      }
   }
}

Config:

• frozen: bool = True

Fields:

• decay (float)

• offset (int)

• scale (int)

• weight (float)

field decay: float = 0.5

Constraints:

• gt = 0

• lt = 1

field offset: int = 1

Constraints:

• ge = 0

field scale: int = 9

Constraints:

• gt = 0

field weight: float = 0.1

Constraints:

• ge = 0

Pydantic models and adapters used to validate reference data.

A validator differs from an anti-corruption service in that it returns information about the parsing process as well as the converted data.

pydantic model app.domain.references.models.validators.EnhancementParseResult

Result of an attempt to parse an enhancement.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "EnhancementParseResult",
   "description": "Result of an attempt to parse an enhancement.",
   "type": "object",
   "properties": {
      "enhancement": {
         "anyOf": [
            {
               "$ref": "#/$defs/EnhancementFileInput"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The enhancement to create"
      },
      "error": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Error encountered during the parsing process",
         "title": "Error"
      }
   },
   "$defs": {
      "AbstractContentEnhancement": {
         "description": "An enhancement which is specific to the abstract of a reference.\n\nThis is separate from the `BibliographicMetadata` for two reasons:\n\n1. Abstracts are increasingly missing from sources like OpenAlex, and may be\nbackfilled from other sources, without the bibliographic metadata.\n2. They are also subject to copyright limitations in ways which metadata are\nnot, and thus need separate visibility controls.",
         "properties": {
            "enhancement_type": {
               "const": "abstract",
               "default": "abstract",
               "title": "Enhancement Type",
               "type": "string"
            },
            "process": {
               "$ref": "#/$defs/AbstractProcessType"
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquire the abstract.",
         "enum": [
            "uninverted",
            "closed_api",
            "other"
         ],
         "title": "AbstractProcessType",
         "type": "string"
      },
      "AnnotationEnhancement": {
         "description": "An enhancement which is composed of a list of Annotations.",
         "properties": {
            "enhancement_type": {
               "const": "annotation",
               "default": "annotation",
               "title": "Enhancement Type",
               "type": "string"
            },
            "annotations": {
               "items": {
                  "discriminator": {
                     "mapping": {
                        "boolean": "#/$defs/BooleanAnnotation",
                        "score": "#/$defs/ScoreAnnotation"
                     },
                     "propertyName": "annotation_type"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/BooleanAnnotation"
                     },
                     {
                        "$ref": "#/$defs/ScoreAnnotation"
                     }
                  ]
               },
               "minItems": 1,
               "title": "Annotations",
               "type": "array"
            }
         },
         "required": [
            "annotations"
         ],
         "title": "AnnotationEnhancement",
         "type": "object"
      },
      "AuthorPosition": {
         "description": "The position of an author in a list of authorships.\n\nMaps to the data from OpenAlex.",
         "enum": [
            "first",
            "middle",
            "last"
         ],
         "title": "AuthorPosition",
         "type": "string"
      },
      "Authorship": {
         "description": "Represents a single author and their association with a reference.\n\nThis is a simplification of the OpenAlex [Authorship\nobject](https://docs.openalex.org/api-entities/works/work-object/authorship-object)\nfor our purposes.",
         "properties": {
            "display_name": {
               "description": "The display name of the author. Expected format FIRSTNAME <MIDDLENAME> LASTNAME. Providing display_name in an unexpected format will affect search performance.",
               "title": "Display Name",
               "type": "string"
            },
            "orcid": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ORCid of the author.",
               "title": "Orcid"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "position"
         ],
         "title": "Authorship",
         "type": "object"
      },
      "BibliographicMetadataEnhancement": {
         "description": "An enhancement which is made up of bibliographic metadata.\n\nGenerally this will be sourced from a database such as OpenAlex or similar.\nFor directly contributed references, these may not be complete.",
         "properties": {
            "enhancement_type": {
               "const": "bibliographic",
               "default": "bibliographic",
               "title": "Enhancement Type",
               "type": "string"
            },
            "authorship": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Authorship"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `Authorships` belonging to this reference.",
               "title": "Authorship"
            },
            "cited_by_count": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex) The number of citations to this work. These are the times that\nother works have cited this work\n",
               "title": "Cited By Count"
            },
            "created_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date this metadata record was created",
               "title": "Created Date"
            },
            "updated_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date of the last OpenAlex update to this metadata",
               "title": "Updated Date"
            },
            "publication_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The date which the version of record was published.",
               "title": "Publication Date"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The year in which the version of record was published.",
               "title": "Publication Year"
            },
            "publisher": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the entity which published the version of record.",
               "title": "Publisher"
            },
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The title of the reference.",
               "title": "Title"
            },
            "pagination": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Pagination"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Pagination info (volume, issue, pages)."
            },
            "publication_venue": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenue"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Publication venue information (journal, repository, etc.)."
            }
         },
         "title": "BibliographicMetadataEnhancement",
         "type": "object"
      },
      "BooleanAnnotation": {
         "description": "An annotation is a way of tagging the content with a label of some kind.\n\nThis class will probably be broken up in the future, but covers most of our\ninitial cases.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "value": {
               "description": "Boolean flag for this annotation",
               "title": "Value",
               "type": "boolean"
            },
            "score": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A confidence score for this annotation",
               "title": "Score"
            },
            "data": {
               "additionalProperties": true,
               "description": "\nAn object representation of the annotation including any confidence scores or\ndescriptions.\n",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "value"
         ],
         "title": "BooleanAnnotation",
         "type": "object"
      },
      "DOIIdentifier": {
         "description": "An external identifier representing a DOI.",
         "properties": {
            "identifier": {
               "description": "The DOI of the reference. Format: '10.<registrant>/<suffix>' where registrant is 4-9 digits and suffix is any non-whitespace characters. Examples: 10.1000/journal.pone.0001, 10.18730/9WQ$D, 10.1000/\u00e9dition",
               "pattern": "^10\\.\\d{4,9}/\\S+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "doi",
               "default": "doi",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "DOIIdentifier",
         "type": "object"
      },
      "DriverVersion": {
         "description": "The version based on the DRIVER guidelines versioning scheme.\n\n(Borrowed from OpenAlex)",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "type": "string"
      },
      "ERICIdentifier": {
         "description": "An external identifier representing an ERIC Number.\n\nAn ERIC Number is defined as a unique identifying number preceded by\nED (for a non-journal document) or EJ (for a journal article).",
         "properties": {
            "identifier": {
               "description": "The ERIC Number. Format: 'ED' or 'EJ' followed by digits. Example: ED123456 or EJ789012",
               "pattern": "E[D|J][0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "eric",
               "default": "eric",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ERICIdentifier",
         "type": "object"
      },
      "EnhancementFileInput": {
         "description": "Enhancement model used to marshall a file input to new references.",
         "properties": {
            "source": {
               "description": "The enhancement source for tracking provenance.",
               "title": "Source",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "description": "The level of visibility of the enhancement"
            },
            "processor_version": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version of the robot that generated the content.",
               "title": "Processor Version"
            },
            "content": {
               "description": "The content of the enhancement.",
               "discriminator": {
                  "mapping": {
                     "abstract": "#/$defs/AbstractContentEnhancement",
                     "annotation": "#/$defs/AnnotationEnhancement",
                     "bibliographic": "#/$defs/BibliographicMetadataEnhancement",
                     "full_text": "#/$defs/FullTextEnhancement",
                     "linked_data": "#/$defs/LinkedDataEnhancement",
                     "location": "#/$defs/LocationEnhancement",
                     "raw": "#/$defs/RawEnhancement",
                     "reference_association": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LinkedDataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/FullTextEnhancement"
                  },
                  {
                     "$ref": "#/$defs/RawEnhancement"
                  }
               ],
               "title": "Content"
            }
         },
         "required": [
            "source",
            "visibility",
            "content"
         ],
         "title": "EnhancementFileInput",
         "type": "object"
      },
      "FullTextEnhancement": {
         "description": "An enhancement for storing a link to the full text and its metadata.\n\nFull texts are not for the sharing of copyrighted material without a license.\nThey are to maintain files for validation and to allow permitted text and data\nmining activities.",
         "properties": {
            "enhancement_type": {
               "const": "full_text",
               "default": "full_text",
               "title": "Enhancement Type",
               "type": "string"
            },
            "file_url": {
               "description": "URL to the full text file",
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "File Url",
               "type": "string"
            },
            "byte_size": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Size of the file in bytes. If provided on import, will be used to validate the file size. Will always be present on enhancements from the repository.",
               "title": "Byte Size"
            },
            "sha256_checksum": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "SHA256 checksum of the file. If provided on import, will be used to verify the integrity of the file. Will always be present on enhancements from the repository.",
               "title": "Sha256 Checksum"
            },
            "mime_type": {
               "default": "application/pdf",
               "description": "The MIME type of the file.",
               "title": "Mime Type",
               "type": "string"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version (according to the DRIVER versioning scheme) of this full text."
            },
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "If this full text is Open Access. May be left as null if this is unknown.",
               "title": "Is Oa"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The publishing license for this full text.",
               "examples": [
                  "apache-2-0",
                  "cc-by",
                  "cc-by-nc",
                  "cc-by-nc-nd",
                  "cc-by-nc-sa",
                  "cc-by-nd",
                  "cc-by-sa",
                  "gpl-v2",
                  "gpl-v3",
                  "isc",
                  "mit",
                  "other-oa",
                  "public-domain"
               ],
               "title": "License"
            },
            "source": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The source from which this full text was obtained.",
               "title": "Source"
            },
            "source_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The URL of the source from which this full text was obtained.",
               "title": "Source Url"
            },
            "retrieved_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp when this full text was retrieved.",
               "title": "Retrieved At"
            }
         },
         "required": [
            "file_url"
         ],
         "title": "FullTextEnhancement",
         "type": "object"
      },
      "JsonValue": {},
      "LinkedDataEnhancement": {
         "description": "An enhancement for storing structured data in a linked data format.\n\nThe content is a JSON-LD document conforming to the vocabulary and\ncontext specified. This enhancement type is produced by mapping robots\nthat transform RawEnhancement data into the shared vocabulary.",
         "properties": {
            "enhancement_type": {
               "const": "linked_data",
               "default": "linked_data",
               "title": "Enhancement Type",
               "type": "string"
            },
            "vocabulary_uri": {
               "description": "The URI of the vocabulary against which this data was produced. Used for compatibility checking.",
               "examples": [
                  "https://vocab.evrepo.org/vocabulary/v1"
               ],
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "Vocabulary Uri",
               "type": "string"
            },
            "data": {
               "additionalProperties": {
                  "$ref": "#/$defs/JsonValue"
               },
               "description": "The JSON-LD content. Must contain an '@context' key with a valid URI string. When combined with the @context, this forms a complete linked data graph.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "vocabulary_uri",
            "data"
         ],
         "title": "LinkedDataEnhancement",
         "type": "object"
      },
      "Location": {
         "description": "A location where a reference can be found.\n\nThis maps almost completely to the OpenAlex\n[Location object](https://docs.openalex.org/api-entities/works/work-object/location-object)",
         "properties": {
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): True if an Open Access (OA) version of this work is available\nat this location. May be left as null if this is unknown (and thus)\ntreated effectively as `false`.\n",
               "title": "Is Oa"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\nThe version (according to the DRIVER versioning scheme) of this location.\n"
            },
            "landing_page_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "(From OpenAlex): The landing page URL for this location.",
               "title": "Landing Page Url"
            },
            "pdf_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): A URL where you can find this location as a PDF.\n",
               "title": "Pdf Url"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): The location's publishing license. This can be a Creative\nCommons license such as cc0 or cc-by, a publisher-specific license, or null\nwhich means we are not able to determine a license for this location.\n",
               "title": "License"
            },
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Any extra metadata about this location",
               "title": "Extra"
            }
         },
         "title": "Location",
         "type": "object"
      },
      "LocationEnhancement": {
         "description": "An enhancement which describes locations where this reference can be found.\n\nThis maps closely (almost exactly) to OpenAlex's locations.",
         "properties": {
            "enhancement_type": {
               "const": "location",
               "default": "location",
               "title": "Enhancement Type",
               "type": "string"
            },
            "locations": {
               "description": "A list of locations where this reference can be found.",
               "items": {
                  "$ref": "#/$defs/Location"
               },
               "minItems": 1,
               "title": "Locations",
               "type": "array"
            }
         },
         "required": [
            "locations"
         ],
         "title": "LocationEnhancement",
         "type": "object"
      },
      "OpenAlexIdentifier": {
         "description": "An external identifier representing an OpenAlex ID.",
         "properties": {
            "identifier": {
               "description": "The OpenAlex ID of the reference. Format: 'W' followed by digits. Example: W2741809807",
               "pattern": "^W\\d+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "open_alex",
               "default": "open_alex",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "OpenAlexIdentifier",
         "type": "object"
      },
      "OtherIdentifier": {
         "description": "An external identifier not otherwise defined by the repository.",
         "properties": {
            "identifier": {
               "description": "The identifier of the reference.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "other",
               "default": "other",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            },
            "other_identifier_name": {
               "description": "The name of the undocumented identifier type.",
               "title": "Other Identifier Name",
               "type": "string"
            }
         },
         "required": [
            "identifier",
            "other_identifier_name"
         ],
         "title": "OtherIdentifier",
         "type": "object"
      },
      "Pagination": {
         "description": "Pagination information for journal articles.\n\nMaps to OpenAlex's work.biblio object. All fields are strings to match\nOpenAlex's format, which may include non-numeric values like \"Spring\" or \"A1\".",
         "properties": {
            "volume": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The volume number of the journal/publication.",
               "title": "Volume"
            },
            "issue": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The issue number of the journal/publication.",
               "title": "Issue"
            },
            "first_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The first page number of the reference in the publication.",
               "title": "First Page"
            },
            "last_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The last page number of the reference in the publication.",
               "title": "Last Page"
            }
         },
         "title": "Pagination",
         "type": "object"
      },
      "ProQuestIdentifier": {
         "description": "An external identifier representing a ProQuest ID.",
         "properties": {
            "identifier": {
               "description": "The ProQuest ID of the reference. Format: numeric digits only. Example: 12345678",
               "pattern": "[0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "pro_quest",
               "default": "pro_quest",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ProQuestIdentifier",
         "type": "object"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID (PMID) of the reference. Example: 12345678",
               "exclusiveMinimum": 0,
               "title": "Identifier",
               "type": "integer"
            },
            "identifier_type": {
               "const": "pm_id",
               "default": "pm_id",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "PubMedIdentifier",
         "type": "object"
      },
      "PublicationVenue": {
         "description": "A publication venue (journal, repository, conference, etc.).",
         "properties": {
            "display_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The display name of the venue (journal name, repository name, etc.)",
               "title": "Display Name"
            },
            "venue_type": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenueType"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The type of venue: journal, repository, book, conference, etc."
            },
            "issn": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of ISSNs associated with this venue (print and electronic)",
               "title": "Issn"
            },
            "issn_l": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The linking ISSN - a canonical ISSN for the venue across format changes",
               "title": "Issn L"
            },
            "host_organization_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Display name of the host organization (publisher)",
               "title": "Host Organization Name"
            }
         },
         "title": "PublicationVenue",
         "type": "object"
      },
      "PublicationVenueType": {
         "description": "Type of publication venue.\n\nAligns with OpenAlex source types.",
         "enum": [
            "journal",
            "repository",
            "conference",
            "ebook_platform",
            "book_series",
            "other"
         ],
         "title": "PublicationVenueType",
         "type": "string"
      },
      "RawEnhancement": {
         "description": "An enhancement for storing raw/arbitrary/unstructured data.\n\nData in these enhancements is intended for future conversion into structured form.\n\nThis enhancement accepts any fields passed in to `data`. These enhancements cannot\nbe created by robots.",
         "properties": {
            "enhancement_type": {
               "const": "raw",
               "default": "raw",
               "title": "Enhancement Type",
               "type": "string"
            },
            "source_export_date": {
               "description": "Date the enhancement data was retrieved.",
               "format": "date-time",
               "title": "Source Export Date",
               "type": "string"
            },
            "description": {
               "description": "Description of the data to aid in future refinement.",
               "title": "Description",
               "type": "string"
            },
            "metadata": {
               "additionalProperties": true,
               "description": "Additional metadata to aid in future structuring of raw data",
               "title": "Metadata",
               "type": "object"
            },
            "data": {
               "description": "Unstructured data for later processing.",
               "title": "Data"
            }
         },
         "required": [
            "source_export_date",
            "description",
            "data"
         ],
         "title": "RawEnhancement",
         "type": "object"
      },
      "ReferenceAssociationEnhancement": {
         "description": "An enhancement for storing associations between references.",
         "properties": {
            "enhancement_type": {
               "const": "reference_association",
               "default": "reference_association",
               "title": "Enhancement Type",
               "type": "string"
            },
            "associated_reference_ids": {
               "description": "A list of Identifiers which are associated to this reference. These can either be ExternalIdentifiers or resolved repository UUID4s.",
               "items": {
                  "anyOf": [
                     {
                        "discriminator": {
                           "mapping": {
                              "doi": "#/$defs/DOIIdentifier",
                              "eric": "#/$defs/ERICIdentifier",
                              "open_alex": "#/$defs/OpenAlexIdentifier",
                              "other": "#/$defs/OtherIdentifier",
                              "pm_id": "#/$defs/PubMedIdentifier",
                              "pro_quest": "#/$defs/ProQuestIdentifier"
                           },
                           "propertyName": "identifier_type"
                        },
                        "oneOf": [
                           {
                              "$ref": "#/$defs/DOIIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ERICIdentifier"
                           },
                           {
                              "$ref": "#/$defs/PubMedIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ProQuestIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OpenAlexIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OtherIdentifier"
                           }
                        ]
                     },
                     {
                        "anyOf": [
                           {
                              "format": "uuid4",
                              "type": "string"
                           },
                           {
                              "format": "uuid7",
                              "type": "string"
                           }
                        ],
                        "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
                     }
                  ]
               },
               "minItems": 1,
               "title": "Associated Reference Ids",
               "type": "array"
            },
            "association_type": {
               "$ref": "#/$defs/ReferenceAssociationType",
               "description": "The type of association between this reference and the associated ones. Direction is important: \"this reference <association_type> associated reference\"."
            }
         },
         "required": [
            "associated_reference_ids",
            "association_type"
         ],
         "title": "ReferenceAssociationEnhancement",
         "type": "object"
      },
      "ReferenceAssociationType": {
         "description": "The type of association between references.\n\nDirection is important: \"this reference <association_type> associated reference\".",
         "enum": [
            "cites",
            "is_cited_by",
            "is_similar_to"
         ],
         "title": "ReferenceAssociationType",
         "type": "string"
      },
      "ScoreAnnotation": {
         "description": "An annotation which represents the score for a label.\n\nThis is similar to a BooleanAnnotation, but lacks a boolean determination\nas to the application of the label.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "score": {
               "description": "Score for this annotation",
               "title": "Score",
               "type": "number"
            },
            "data": {
               "additionalProperties": true,
               "description": "An object representation of the annotation including any confidence scores or descriptions.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "score"
         ],
         "title": "ScoreAnnotation",
         "type": "object"
      },
      "Visibility": {
         "description": "The visibility of a data element in the repository.\n\nThis is used to manage whether information should be publicly available or\nrestricted (generally due to copyright constraints from publishers).",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   }
}

Fields:

• enhancement (destiny_sdk.enhancements.EnhancementFileInput | None)

• error (str | None)

field enhancement: EnhancementFileInput | None = None

The enhancement to create

field error: str | None = None

Error encountered during the parsing process

classmethod from_raw(raw_enhancement: JSON, entry_ref: int) → Self

Parse an enhancement from raw JSON.

pydantic model app.domain.references.models.validators.EnhancementResultValidator

Result of a batch enhancement request.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "EnhancementResultValidator",
   "description": "Result of a batch enhancement request.",
   "type": "object",
   "properties": {
      "enhancement_to_add": {
         "anyOf": [
            {
               "$ref": "#/$defs/Enhancement"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "An enhancement to add to the references"
      },
      "robot_error": {
         "anyOf": [
            {
               "$ref": "#/$defs/LinkedRobotError"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "An error encountered by the robot during processing"
      },
      "parse_failure": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "An error encountered while parsing the batch enhancement result",
         "title": "Parse Failure"
      }
   },
   "$defs": {
      "AbstractContentEnhancement": {
         "description": "An enhancement which is specific to the abstract of a reference.\n\nThis is separate from the `BibliographicMetadata` for two reasons:\n\n1. Abstracts are increasingly missing from sources like OpenAlex, and may be\nbackfilled from other sources, without the bibliographic metadata.\n2. They are also subject to copyright limitations in ways which metadata are\nnot, and thus need separate visibility controls.",
         "properties": {
            "enhancement_type": {
               "const": "abstract",
               "default": "abstract",
               "title": "Enhancement Type",
               "type": "string"
            },
            "process": {
               "$ref": "#/$defs/AbstractProcessType"
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquire the abstract.",
         "enum": [
            "uninverted",
            "closed_api",
            "other"
         ],
         "title": "AbstractProcessType",
         "type": "string"
      },
      "AnnotationEnhancement": {
         "description": "An enhancement which is composed of a list of Annotations.",
         "properties": {
            "enhancement_type": {
               "const": "annotation",
               "default": "annotation",
               "title": "Enhancement Type",
               "type": "string"
            },
            "annotations": {
               "items": {
                  "discriminator": {
                     "mapping": {
                        "boolean": "#/$defs/BooleanAnnotation",
                        "score": "#/$defs/ScoreAnnotation"
                     },
                     "propertyName": "annotation_type"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/BooleanAnnotation"
                     },
                     {
                        "$ref": "#/$defs/ScoreAnnotation"
                     }
                  ]
               },
               "minItems": 1,
               "title": "Annotations",
               "type": "array"
            }
         },
         "required": [
            "annotations"
         ],
         "title": "AnnotationEnhancement",
         "type": "object"
      },
      "AuthorPosition": {
         "description": "The position of an author in a list of authorships.\n\nMaps to the data from OpenAlex.",
         "enum": [
            "first",
            "middle",
            "last"
         ],
         "title": "AuthorPosition",
         "type": "string"
      },
      "Authorship": {
         "description": "Represents a single author and their association with a reference.\n\nThis is a simplification of the OpenAlex [Authorship\nobject](https://docs.openalex.org/api-entities/works/work-object/authorship-object)\nfor our purposes.",
         "properties": {
            "display_name": {
               "description": "The display name of the author. Expected format FIRSTNAME <MIDDLENAME> LASTNAME. Providing display_name in an unexpected format will affect search performance.",
               "title": "Display Name",
               "type": "string"
            },
            "orcid": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ORCid of the author.",
               "title": "Orcid"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "position"
         ],
         "title": "Authorship",
         "type": "object"
      },
      "BibliographicMetadataEnhancement": {
         "description": "An enhancement which is made up of bibliographic metadata.\n\nGenerally this will be sourced from a database such as OpenAlex or similar.\nFor directly contributed references, these may not be complete.",
         "properties": {
            "enhancement_type": {
               "const": "bibliographic",
               "default": "bibliographic",
               "title": "Enhancement Type",
               "type": "string"
            },
            "authorship": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Authorship"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `Authorships` belonging to this reference.",
               "title": "Authorship"
            },
            "cited_by_count": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex) The number of citations to this work. These are the times that\nother works have cited this work\n",
               "title": "Cited By Count"
            },
            "created_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date this metadata record was created",
               "title": "Created Date"
            },
            "updated_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date of the last OpenAlex update to this metadata",
               "title": "Updated Date"
            },
            "publication_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The date which the version of record was published.",
               "title": "Publication Date"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The year in which the version of record was published.",
               "title": "Publication Year"
            },
            "publisher": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the entity which published the version of record.",
               "title": "Publisher"
            },
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The title of the reference.",
               "title": "Title"
            },
            "pagination": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Pagination"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Pagination info (volume, issue, pages)."
            },
            "publication_venue": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenue"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Publication venue information (journal, repository, etc.)."
            }
         },
         "title": "BibliographicMetadataEnhancement",
         "type": "object"
      },
      "BooleanAnnotation": {
         "description": "An annotation is a way of tagging the content with a label of some kind.\n\nThis class will probably be broken up in the future, but covers most of our\ninitial cases.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "value": {
               "description": "Boolean flag for this annotation",
               "title": "Value",
               "type": "boolean"
            },
            "score": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A confidence score for this annotation",
               "title": "Score"
            },
            "data": {
               "additionalProperties": true,
               "description": "\nAn object representation of the annotation including any confidence scores or\ndescriptions.\n",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "value"
         ],
         "title": "BooleanAnnotation",
         "type": "object"
      },
      "DOIIdentifier": {
         "description": "An external identifier representing a DOI.",
         "properties": {
            "identifier": {
               "description": "The DOI of the reference. Format: '10.<registrant>/<suffix>' where registrant is 4-9 digits and suffix is any non-whitespace characters. Examples: 10.1000/journal.pone.0001, 10.18730/9WQ$D, 10.1000/\u00e9dition",
               "pattern": "^10\\.\\d{4,9}/\\S+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "doi",
               "default": "doi",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "DOIIdentifier",
         "type": "object"
      },
      "DriverVersion": {
         "description": "The version based on the DRIVER guidelines versioning scheme.\n\n(Borrowed from OpenAlex)",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "type": "string"
      },
      "ERICIdentifier": {
         "description": "An external identifier representing an ERIC Number.\n\nAn ERIC Number is defined as a unique identifying number preceded by\nED (for a non-journal document) or EJ (for a journal article).",
         "properties": {
            "identifier": {
               "description": "The ERIC Number. Format: 'ED' or 'EJ' followed by digits. Example: ED123456 or EJ789012",
               "pattern": "E[D|J][0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "eric",
               "default": "eric",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ERICIdentifier",
         "type": "object"
      },
      "Enhancement": {
         "description": "Core enhancement class.",
         "properties": {
            "id": {
               "anyOf": [
                  {
                     "anyOf": [
                        {
                           "format": "uuid4",
                           "type": "string"
                        },
                        {
                           "format": "uuid7",
                           "type": "string"
                        }
                     ],
                     "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the enhancement. Populated by the repository when sending enhancements with references.",
               "title": "Id"
            },
            "reference_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "type": "string"
                  },
                  {
                     "format": "uuid7",
                     "type": "string"
                  }
               ],
               "description": "The ID of the reference this enhancement is associated with.",
               "title": "Reference Id"
            },
            "source": {
               "description": "The enhancement source for tracking provenance.",
               "title": "Source",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "description": "The level of visibility of the enhancement"
            },
            "robot_version": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version of the robot that generated the content.",
               "title": "Robot Version"
            },
            "derived_from": {
               "anyOf": [
                  {
                     "items": {
                        "anyOf": [
                           {
                              "format": "uuid4",
                              "type": "string"
                           },
                           {
                              "format": "uuid7",
                              "type": "string"
                           }
                        ],
                        "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of enhancement IDs that this enhancement was derived from.",
               "title": "Derived From"
            },
            "content": {
               "description": "The content of the enhancement.",
               "discriminator": {
                  "mapping": {
                     "abstract": "#/$defs/AbstractContentEnhancement",
                     "annotation": "#/$defs/AnnotationEnhancement",
                     "bibliographic": "#/$defs/BibliographicMetadataEnhancement",
                     "full_text": "#/$defs/FullTextEnhancement",
                     "linked_data": "#/$defs/LinkedDataEnhancement",
                     "location": "#/$defs/LocationEnhancement",
                     "raw": "#/$defs/RawEnhancement",
                     "reference_association": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LinkedDataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/FullTextEnhancement"
                  },
                  {
                     "$ref": "#/$defs/RawEnhancement"
                  }
               ],
               "title": "Content"
            },
            "created_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 datetime when the enhancement was added to the repository. This field is populated by the repository, if it is included on an incoming enhancement it will be ignored.",
               "title": "Created At"
            }
         },
         "required": [
            "reference_id",
            "source",
            "visibility",
            "content"
         ],
         "title": "Enhancement",
         "type": "object"
      },
      "FullTextEnhancement": {
         "description": "An enhancement for storing a link to the full text and its metadata.\n\nFull texts are not for the sharing of copyrighted material without a license.\nThey are to maintain files for validation and to allow permitted text and data\nmining activities.",
         "properties": {
            "enhancement_type": {
               "const": "full_text",
               "default": "full_text",
               "title": "Enhancement Type",
               "type": "string"
            },
            "file_url": {
               "description": "URL to the full text file",
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "File Url",
               "type": "string"
            },
            "byte_size": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Size of the file in bytes. If provided on import, will be used to validate the file size. Will always be present on enhancements from the repository.",
               "title": "Byte Size"
            },
            "sha256_checksum": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "SHA256 checksum of the file. If provided on import, will be used to verify the integrity of the file. Will always be present on enhancements from the repository.",
               "title": "Sha256 Checksum"
            },
            "mime_type": {
               "default": "application/pdf",
               "description": "The MIME type of the file.",
               "title": "Mime Type",
               "type": "string"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version (according to the DRIVER versioning scheme) of this full text."
            },
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "If this full text is Open Access. May be left as null if this is unknown.",
               "title": "Is Oa"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The publishing license for this full text.",
               "examples": [
                  "apache-2-0",
                  "cc-by",
                  "cc-by-nc",
                  "cc-by-nc-nd",
                  "cc-by-nc-sa",
                  "cc-by-nd",
                  "cc-by-sa",
                  "gpl-v2",
                  "gpl-v3",
                  "isc",
                  "mit",
                  "other-oa",
                  "public-domain"
               ],
               "title": "License"
            },
            "source": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The source from which this full text was obtained.",
               "title": "Source"
            },
            "source_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The URL of the source from which this full text was obtained.",
               "title": "Source Url"
            },
            "retrieved_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp when this full text was retrieved.",
               "title": "Retrieved At"
            }
         },
         "required": [
            "file_url"
         ],
         "title": "FullTextEnhancement",
         "type": "object"
      },
      "JsonValue": {},
      "LinkedDataEnhancement": {
         "description": "An enhancement for storing structured data in a linked data format.\n\nThe content is a JSON-LD document conforming to the vocabulary and\ncontext specified. This enhancement type is produced by mapping robots\nthat transform RawEnhancement data into the shared vocabulary.",
         "properties": {
            "enhancement_type": {
               "const": "linked_data",
               "default": "linked_data",
               "title": "Enhancement Type",
               "type": "string"
            },
            "vocabulary_uri": {
               "description": "The URI of the vocabulary against which this data was produced. Used for compatibility checking.",
               "examples": [
                  "https://vocab.evrepo.org/vocabulary/v1"
               ],
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "Vocabulary Uri",
               "type": "string"
            },
            "data": {
               "additionalProperties": {
                  "$ref": "#/$defs/JsonValue"
               },
               "description": "The JSON-LD content. Must contain an '@context' key with a valid URI string. When combined with the @context, this forms a complete linked data graph.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "vocabulary_uri",
            "data"
         ],
         "title": "LinkedDataEnhancement",
         "type": "object"
      },
      "LinkedRobotError": {
         "description": "A record of something going wrong when processing an individual reference.\n\nUsed in results for batch requests - in single requests, the reference\nid is derived from the request id.",
         "properties": {
            "message": {
               "description": "Message which describes the error encountered during processing",
               "title": "Message",
               "type": "string"
            },
            "reference_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "type": "string"
                  },
                  {
                     "format": "uuid7",
                     "type": "string"
                  }
               ],
               "description": "The ID of the reference which caused the error.",
               "title": "Reference Id"
            }
         },
         "required": [
            "message",
            "reference_id"
         ],
         "title": "LinkedRobotError",
         "type": "object"
      },
      "Location": {
         "description": "A location where a reference can be found.\n\nThis maps almost completely to the OpenAlex\n[Location object](https://docs.openalex.org/api-entities/works/work-object/location-object)",
         "properties": {
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): True if an Open Access (OA) version of this work is available\nat this location. May be left as null if this is unknown (and thus)\ntreated effectively as `false`.\n",
               "title": "Is Oa"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\nThe version (according to the DRIVER versioning scheme) of this location.\n"
            },
            "landing_page_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "(From OpenAlex): The landing page URL for this location.",
               "title": "Landing Page Url"
            },
            "pdf_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): A URL where you can find this location as a PDF.\n",
               "title": "Pdf Url"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): The location's publishing license. This can be a Creative\nCommons license such as cc0 or cc-by, a publisher-specific license, or null\nwhich means we are not able to determine a license for this location.\n",
               "title": "License"
            },
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Any extra metadata about this location",
               "title": "Extra"
            }
         },
         "title": "Location",
         "type": "object"
      },
      "LocationEnhancement": {
         "description": "An enhancement which describes locations where this reference can be found.\n\nThis maps closely (almost exactly) to OpenAlex's locations.",
         "properties": {
            "enhancement_type": {
               "const": "location",
               "default": "location",
               "title": "Enhancement Type",
               "type": "string"
            },
            "locations": {
               "description": "A list of locations where this reference can be found.",
               "items": {
                  "$ref": "#/$defs/Location"
               },
               "minItems": 1,
               "title": "Locations",
               "type": "array"
            }
         },
         "required": [
            "locations"
         ],
         "title": "LocationEnhancement",
         "type": "object"
      },
      "OpenAlexIdentifier": {
         "description": "An external identifier representing an OpenAlex ID.",
         "properties": {
            "identifier": {
               "description": "The OpenAlex ID of the reference. Format: 'W' followed by digits. Example: W2741809807",
               "pattern": "^W\\d+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "open_alex",
               "default": "open_alex",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "OpenAlexIdentifier",
         "type": "object"
      },
      "OtherIdentifier": {
         "description": "An external identifier not otherwise defined by the repository.",
         "properties": {
            "identifier": {
               "description": "The identifier of the reference.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "other",
               "default": "other",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            },
            "other_identifier_name": {
               "description": "The name of the undocumented identifier type.",
               "title": "Other Identifier Name",
               "type": "string"
            }
         },
         "required": [
            "identifier",
            "other_identifier_name"
         ],
         "title": "OtherIdentifier",
         "type": "object"
      },
      "Pagination": {
         "description": "Pagination information for journal articles.\n\nMaps to OpenAlex's work.biblio object. All fields are strings to match\nOpenAlex's format, which may include non-numeric values like \"Spring\" or \"A1\".",
         "properties": {
            "volume": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The volume number of the journal/publication.",
               "title": "Volume"
            },
            "issue": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The issue number of the journal/publication.",
               "title": "Issue"
            },
            "first_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The first page number of the reference in the publication.",
               "title": "First Page"
            },
            "last_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The last page number of the reference in the publication.",
               "title": "Last Page"
            }
         },
         "title": "Pagination",
         "type": "object"
      },
      "ProQuestIdentifier": {
         "description": "An external identifier representing a ProQuest ID.",
         "properties": {
            "identifier": {
               "description": "The ProQuest ID of the reference. Format: numeric digits only. Example: 12345678",
               "pattern": "[0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "pro_quest",
               "default": "pro_quest",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ProQuestIdentifier",
         "type": "object"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID (PMID) of the reference. Example: 12345678",
               "exclusiveMinimum": 0,
               "title": "Identifier",
               "type": "integer"
            },
            "identifier_type": {
               "const": "pm_id",
               "default": "pm_id",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "PubMedIdentifier",
         "type": "object"
      },
      "PublicationVenue": {
         "description": "A publication venue (journal, repository, conference, etc.).",
         "properties": {
            "display_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The display name of the venue (journal name, repository name, etc.)",
               "title": "Display Name"
            },
            "venue_type": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenueType"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The type of venue: journal, repository, book, conference, etc."
            },
            "issn": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of ISSNs associated with this venue (print and electronic)",
               "title": "Issn"
            },
            "issn_l": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The linking ISSN - a canonical ISSN for the venue across format changes",
               "title": "Issn L"
            },
            "host_organization_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Display name of the host organization (publisher)",
               "title": "Host Organization Name"
            }
         },
         "title": "PublicationVenue",
         "type": "object"
      },
      "PublicationVenueType": {
         "description": "Type of publication venue.\n\nAligns with OpenAlex source types.",
         "enum": [
            "journal",
            "repository",
            "conference",
            "ebook_platform",
            "book_series",
            "other"
         ],
         "title": "PublicationVenueType",
         "type": "string"
      },
      "RawEnhancement": {
         "description": "An enhancement for storing raw/arbitrary/unstructured data.\n\nData in these enhancements is intended for future conversion into structured form.\n\nThis enhancement accepts any fields passed in to `data`. These enhancements cannot\nbe created by robots.",
         "properties": {
            "enhancement_type": {
               "const": "raw",
               "default": "raw",
               "title": "Enhancement Type",
               "type": "string"
            },
            "source_export_date": {
               "description": "Date the enhancement data was retrieved.",
               "format": "date-time",
               "title": "Source Export Date",
               "type": "string"
            },
            "description": {
               "description": "Description of the data to aid in future refinement.",
               "title": "Description",
               "type": "string"
            },
            "metadata": {
               "additionalProperties": true,
               "description": "Additional metadata to aid in future structuring of raw data",
               "title": "Metadata",
               "type": "object"
            },
            "data": {
               "description": "Unstructured data for later processing.",
               "title": "Data"
            }
         },
         "required": [
            "source_export_date",
            "description",
            "data"
         ],
         "title": "RawEnhancement",
         "type": "object"
      },
      "ReferenceAssociationEnhancement": {
         "description": "An enhancement for storing associations between references.",
         "properties": {
            "enhancement_type": {
               "const": "reference_association",
               "default": "reference_association",
               "title": "Enhancement Type",
               "type": "string"
            },
            "associated_reference_ids": {
               "description": "A list of Identifiers which are associated to this reference. These can either be ExternalIdentifiers or resolved repository UUID4s.",
               "items": {
                  "anyOf": [
                     {
                        "discriminator": {
                           "mapping": {
                              "doi": "#/$defs/DOIIdentifier",
                              "eric": "#/$defs/ERICIdentifier",
                              "open_alex": "#/$defs/OpenAlexIdentifier",
                              "other": "#/$defs/OtherIdentifier",
                              "pm_id": "#/$defs/PubMedIdentifier",
                              "pro_quest": "#/$defs/ProQuestIdentifier"
                           },
                           "propertyName": "identifier_type"
                        },
                        "oneOf": [
                           {
                              "$ref": "#/$defs/DOIIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ERICIdentifier"
                           },
                           {
                              "$ref": "#/$defs/PubMedIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ProQuestIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OpenAlexIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OtherIdentifier"
                           }
                        ]
                     },
                     {
                        "anyOf": [
                           {
                              "format": "uuid4",
                              "type": "string"
                           },
                           {
                              "format": "uuid7",
                              "type": "string"
                           }
                        ],
                        "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
                     }
                  ]
               },
               "minItems": 1,
               "title": "Associated Reference Ids",
               "type": "array"
            },
            "association_type": {
               "$ref": "#/$defs/ReferenceAssociationType",
               "description": "The type of association between this reference and the associated ones. Direction is important: \"this reference <association_type> associated reference\"."
            }
         },
         "required": [
            "associated_reference_ids",
            "association_type"
         ],
         "title": "ReferenceAssociationEnhancement",
         "type": "object"
      },
      "ReferenceAssociationType": {
         "description": "The type of association between references.\n\nDirection is important: \"this reference <association_type> associated reference\".",
         "enum": [
            "cites",
            "is_cited_by",
            "is_similar_to"
         ],
         "title": "ReferenceAssociationType",
         "type": "string"
      },
      "ScoreAnnotation": {
         "description": "An annotation which represents the score for a label.\n\nThis is similar to a BooleanAnnotation, but lacks a boolean determination\nas to the application of the label.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "score": {
               "description": "Score for this annotation",
               "title": "Score",
               "type": "number"
            },
            "data": {
               "additionalProperties": true,
               "description": "An object representation of the annotation including any confidence scores or descriptions.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "score"
         ],
         "title": "ScoreAnnotation",
         "type": "object"
      },
      "Visibility": {
         "description": "The visibility of a data element in the repository.\n\nThis is used to manage whether information should be publicly available or\nrestricted (generally due to copyright constraints from publishers).",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   }
}

Fields:

• enhancement_to_add (destiny_sdk.enhancements.Enhancement | None)

• parse_failure (str | None)

• robot_error (destiny_sdk.robots.LinkedRobotError | None)

field enhancement_to_add: Enhancement | None = None

An enhancement to add to the references

field parse_failure: str | None = None

An error encountered while parsing the batch enhancement result

field robot_error: LinkedRobotError | None = None

An error encountered by the robot during processing

classmethod from_raw(entry: str, entry_ref: int, expected_reference_ids: set[UUID], processed_reference_ids: set[UUID] | None = None) → Self

Create a EnhancementResult from a jsonl entry.

pydantic model app.domain.references.models.validators.ExternalIdentifierParseResult

Result of an attempt to parse an external identifier.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ExternalIdentifierParseResult",
   "description": "Result of an attempt to parse an external identifier.",
   "type": "object",
   "properties": {
      "external_identifier": {
         "anyOf": [
            {
               "discriminator": {
                  "mapping": {
                     "doi": "#/$defs/DOIIdentifier",
                     "eric": "#/$defs/ERICIdentifier",
                     "open_alex": "#/$defs/OpenAlexIdentifier",
                     "other": "#/$defs/OtherIdentifier",
                     "pm_id": "#/$defs/PubMedIdentifier",
                     "pro_quest": "#/$defs/ProQuestIdentifier"
                  },
                  "propertyName": "identifier_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/DOIIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ERICIdentifier"
                  },
                  {
                     "$ref": "#/$defs/PubMedIdentifier"
                  },
                  {
                     "$ref": "#/$defs/ProQuestIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OpenAlexIdentifier"
                  },
                  {
                     "$ref": "#/$defs/OtherIdentifier"
                  }
               ]
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The external identifier to create",
         "title": "External Identifier"
      },
      "error": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Error encountered during the parsing process",
         "title": "Error"
      }
   },
   "$defs": {
      "DOIIdentifier": {
         "description": "An external identifier representing a DOI.",
         "properties": {
            "identifier": {
               "description": "The DOI of the reference. Format: '10.<registrant>/<suffix>' where registrant is 4-9 digits and suffix is any non-whitespace characters. Examples: 10.1000/journal.pone.0001, 10.18730/9WQ$D, 10.1000/\u00e9dition",
               "pattern": "^10\\.\\d{4,9}/\\S+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "doi",
               "default": "doi",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "DOIIdentifier",
         "type": "object"
      },
      "ERICIdentifier": {
         "description": "An external identifier representing an ERIC Number.\n\nAn ERIC Number is defined as a unique identifying number preceded by\nED (for a non-journal document) or EJ (for a journal article).",
         "properties": {
            "identifier": {
               "description": "The ERIC Number. Format: 'ED' or 'EJ' followed by digits. Example: ED123456 or EJ789012",
               "pattern": "E[D|J][0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "eric",
               "default": "eric",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ERICIdentifier",
         "type": "object"
      },
      "OpenAlexIdentifier": {
         "description": "An external identifier representing an OpenAlex ID.",
         "properties": {
            "identifier": {
               "description": "The OpenAlex ID of the reference. Format: 'W' followed by digits. Example: W2741809807",
               "pattern": "^W\\d+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "open_alex",
               "default": "open_alex",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "OpenAlexIdentifier",
         "type": "object"
      },
      "OtherIdentifier": {
         "description": "An external identifier not otherwise defined by the repository.",
         "properties": {
            "identifier": {
               "description": "The identifier of the reference.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "other",
               "default": "other",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            },
            "other_identifier_name": {
               "description": "The name of the undocumented identifier type.",
               "title": "Other Identifier Name",
               "type": "string"
            }
         },
         "required": [
            "identifier",
            "other_identifier_name"
         ],
         "title": "OtherIdentifier",
         "type": "object"
      },
      "ProQuestIdentifier": {
         "description": "An external identifier representing a ProQuest ID.",
         "properties": {
            "identifier": {
               "description": "The ProQuest ID of the reference. Format: numeric digits only. Example: 12345678",
               "pattern": "[0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "pro_quest",
               "default": "pro_quest",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ProQuestIdentifier",
         "type": "object"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID (PMID) of the reference. Example: 12345678",
               "exclusiveMinimum": 0,
               "title": "Identifier",
               "type": "integer"
            },
            "identifier_type": {
               "const": "pm_id",
               "default": "pm_id",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "PubMedIdentifier",
         "type": "object"
      }
   }
}

Fields:

• error (str | None)

• external_identifier (destiny_sdk.identifiers.DOIIdentifier | destiny_sdk.identifiers.ERICIdentifier | destiny_sdk.identifiers.PubMedIdentifier | destiny_sdk.identifiers.ProQuestIdentifier | destiny_sdk.identifiers.OpenAlexIdentifier | destiny_sdk.identifiers.OtherIdentifier | None)

field error: str | None = None

Error encountered during the parsing process

field external_identifier: Annotated[DOIIdentifier | ERICIdentifier | PubMedIdentifier | ProQuestIdentifier | OpenAlexIdentifier | OtherIdentifier, FieldInfo(annotation=NoneType, required=True, discriminator='identifier_type')] | None = None

The external identifier to create

classmethod from_raw(raw_identifier: JSON, entry_ref: int) → Self

Parse an external identifier from raw JSON.

pydantic model app.domain.references.models.validators.ReferenceCreateResult

Result of an attempt to create a reference.

If reference is None, no reference was created and errors will be populated. If reference exists and there are errors, the reference was created but there were errors in the hydration. If reference exists and there are no errors, the reference was created and all enhancements/identifiers were hydrated successfully from the input. If duplicate_decision_id is set, the reference is pending deduplication.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ReferenceCreateResult",
   "description": "Result of an attempt to create a reference.\n\nIf reference is None, no reference was created and errors will be populated.\nIf reference exists and there are errors, the reference was created but there\nwere errors in the hydration.\nIf reference exists and there are no errors, the reference was created and all\nenhancements/identifiers were hydrated successfully from the input.\nIf duplicate_decision_id is set, the reference is pending deduplication.",
   "type": "object",
   "properties": {
      "reference": {
         "anyOf": [
            {
               "$ref": "#/$defs/ReferenceFileInput"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The validated reference input."
      },
      "errors": {
         "description": "A list of errors encountered during the creation process",
         "items": {
            "type": "string"
         },
         "title": "Errors",
         "type": "array"
      },
      "reference_id": {
         "anyOf": [
            {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "type": "string"
                  },
                  {
                     "format": "uuid7",
                     "type": "string"
                  }
               ],
               "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The ID of the created reference, if created",
         "title": "Reference Id"
      },
      "duplicate_decision_id": {
         "anyOf": [
            {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "type": "string"
                  },
                  {
                     "format": "uuid7",
                     "type": "string"
                  }
               ],
               "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The ID of the pending duplicate decision, if required",
         "title": "Duplicate Decision Id"
      }
   },
   "$defs": {
      "AbstractContentEnhancement": {
         "description": "An enhancement which is specific to the abstract of a reference.\n\nThis is separate from the `BibliographicMetadata` for two reasons:\n\n1. Abstracts are increasingly missing from sources like OpenAlex, and may be\nbackfilled from other sources, without the bibliographic metadata.\n2. They are also subject to copyright limitations in ways which metadata are\nnot, and thus need separate visibility controls.",
         "properties": {
            "enhancement_type": {
               "const": "abstract",
               "default": "abstract",
               "title": "Enhancement Type",
               "type": "string"
            },
            "process": {
               "$ref": "#/$defs/AbstractProcessType"
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquire the abstract.",
         "enum": [
            "uninverted",
            "closed_api",
            "other"
         ],
         "title": "AbstractProcessType",
         "type": "string"
      },
      "AnnotationEnhancement": {
         "description": "An enhancement which is composed of a list of Annotations.",
         "properties": {
            "enhancement_type": {
               "const": "annotation",
               "default": "annotation",
               "title": "Enhancement Type",
               "type": "string"
            },
            "annotations": {
               "items": {
                  "discriminator": {
                     "mapping": {
                        "boolean": "#/$defs/BooleanAnnotation",
                        "score": "#/$defs/ScoreAnnotation"
                     },
                     "propertyName": "annotation_type"
                  },
                  "oneOf": [
                     {
                        "$ref": "#/$defs/BooleanAnnotation"
                     },
                     {
                        "$ref": "#/$defs/ScoreAnnotation"
                     }
                  ]
               },
               "minItems": 1,
               "title": "Annotations",
               "type": "array"
            }
         },
         "required": [
            "annotations"
         ],
         "title": "AnnotationEnhancement",
         "type": "object"
      },
      "AuthorPosition": {
         "description": "The position of an author in a list of authorships.\n\nMaps to the data from OpenAlex.",
         "enum": [
            "first",
            "middle",
            "last"
         ],
         "title": "AuthorPosition",
         "type": "string"
      },
      "Authorship": {
         "description": "Represents a single author and their association with a reference.\n\nThis is a simplification of the OpenAlex [Authorship\nobject](https://docs.openalex.org/api-entities/works/work-object/authorship-object)\nfor our purposes.",
         "properties": {
            "display_name": {
               "description": "The display name of the author. Expected format FIRSTNAME <MIDDLENAME> LASTNAME. Providing display_name in an unexpected format will affect search performance.",
               "title": "Display Name",
               "type": "string"
            },
            "orcid": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ORCid of the author.",
               "title": "Orcid"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "position"
         ],
         "title": "Authorship",
         "type": "object"
      },
      "BibliographicMetadataEnhancement": {
         "description": "An enhancement which is made up of bibliographic metadata.\n\nGenerally this will be sourced from a database such as OpenAlex or similar.\nFor directly contributed references, these may not be complete.",
         "properties": {
            "enhancement_type": {
               "const": "bibliographic",
               "default": "bibliographic",
               "title": "Enhancement Type",
               "type": "string"
            },
            "authorship": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Authorship"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `Authorships` belonging to this reference.",
               "title": "Authorship"
            },
            "cited_by_count": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex) The number of citations to this work. These are the times that\nother works have cited this work\n",
               "title": "Cited By Count"
            },
            "created_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date this metadata record was created",
               "title": "Created Date"
            },
            "updated_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ISO8601 date of the last OpenAlex update to this metadata",
               "title": "Updated Date"
            },
            "publication_date": {
               "anyOf": [
                  {
                     "format": "date",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The date which the version of record was published.",
               "title": "Publication Date"
            },
            "publication_year": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The year in which the version of record was published.",
               "title": "Publication Year"
            },
            "publisher": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The name of the entity which published the version of record.",
               "title": "Publisher"
            },
            "title": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The title of the reference.",
               "title": "Title"
            },
            "pagination": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/Pagination"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Pagination info (volume, issue, pages)."
            },
            "publication_venue": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenue"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Publication venue information (journal, repository, etc.)."
            }
         },
         "title": "BibliographicMetadataEnhancement",
         "type": "object"
      },
      "BooleanAnnotation": {
         "description": "An annotation is a way of tagging the content with a label of some kind.\n\nThis class will probably be broken up in the future, but covers most of our\ninitial cases.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "value": {
               "description": "Boolean flag for this annotation",
               "title": "Value",
               "type": "boolean"
            },
            "score": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A confidence score for this annotation",
               "title": "Score"
            },
            "data": {
               "additionalProperties": true,
               "description": "\nAn object representation of the annotation including any confidence scores or\ndescriptions.\n",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "value"
         ],
         "title": "BooleanAnnotation",
         "type": "object"
      },
      "DOIIdentifier": {
         "description": "An external identifier representing a DOI.",
         "properties": {
            "identifier": {
               "description": "The DOI of the reference. Format: '10.<registrant>/<suffix>' where registrant is 4-9 digits and suffix is any non-whitespace characters. Examples: 10.1000/journal.pone.0001, 10.18730/9WQ$D, 10.1000/\u00e9dition",
               "pattern": "^10\\.\\d{4,9}/\\S+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "doi",
               "default": "doi",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "DOIIdentifier",
         "type": "object"
      },
      "DriverVersion": {
         "description": "The version based on the DRIVER guidelines versioning scheme.\n\n(Borrowed from OpenAlex)",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "type": "string"
      },
      "ERICIdentifier": {
         "description": "An external identifier representing an ERIC Number.\n\nAn ERIC Number is defined as a unique identifying number preceded by\nED (for a non-journal document) or EJ (for a journal article).",
         "properties": {
            "identifier": {
               "description": "The ERIC Number. Format: 'ED' or 'EJ' followed by digits. Example: ED123456 or EJ789012",
               "pattern": "E[D|J][0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "eric",
               "default": "eric",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ERICIdentifier",
         "type": "object"
      },
      "EnhancementFileInput": {
         "description": "Enhancement model used to marshall a file input to new references.",
         "properties": {
            "source": {
               "description": "The enhancement source for tracking provenance.",
               "title": "Source",
               "type": "string"
            },
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "description": "The level of visibility of the enhancement"
            },
            "processor_version": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version of the robot that generated the content.",
               "title": "Processor Version"
            },
            "content": {
               "description": "The content of the enhancement.",
               "discriminator": {
                  "mapping": {
                     "abstract": "#/$defs/AbstractContentEnhancement",
                     "annotation": "#/$defs/AnnotationEnhancement",
                     "bibliographic": "#/$defs/BibliographicMetadataEnhancement",
                     "full_text": "#/$defs/FullTextEnhancement",
                     "linked_data": "#/$defs/LinkedDataEnhancement",
                     "location": "#/$defs/LocationEnhancement",
                     "raw": "#/$defs/RawEnhancement",
                     "reference_association": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/ReferenceAssociationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LinkedDataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/FullTextEnhancement"
                  },
                  {
                     "$ref": "#/$defs/RawEnhancement"
                  }
               ],
               "title": "Content"
            }
         },
         "required": [
            "source",
            "visibility",
            "content"
         ],
         "title": "EnhancementFileInput",
         "type": "object"
      },
      "FullTextEnhancement": {
         "description": "An enhancement for storing a link to the full text and its metadata.\n\nFull texts are not for the sharing of copyrighted material without a license.\nThey are to maintain files for validation and to allow permitted text and data\nmining activities.",
         "properties": {
            "enhancement_type": {
               "const": "full_text",
               "default": "full_text",
               "title": "Enhancement Type",
               "type": "string"
            },
            "file_url": {
               "description": "URL to the full text file",
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "File Url",
               "type": "string"
            },
            "byte_size": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Size of the file in bytes. If provided on import, will be used to validate the file size. Will always be present on enhancements from the repository.",
               "title": "Byte Size"
            },
            "sha256_checksum": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "SHA256 checksum of the file. If provided on import, will be used to verify the integrity of the file. Will always be present on enhancements from the repository.",
               "title": "Sha256 Checksum"
            },
            "mime_type": {
               "default": "application/pdf",
               "description": "The MIME type of the file.",
               "title": "Mime Type",
               "type": "string"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The version (according to the DRIVER versioning scheme) of this full text."
            },
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "If this full text is Open Access. May be left as null if this is unknown.",
               "title": "Is Oa"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The publishing license for this full text.",
               "examples": [
                  "apache-2-0",
                  "cc-by",
                  "cc-by-nc",
                  "cc-by-nc-nd",
                  "cc-by-nc-sa",
                  "cc-by-nd",
                  "cc-by-sa",
                  "gpl-v2",
                  "gpl-v3",
                  "isc",
                  "mit",
                  "other-oa",
                  "public-domain"
               ],
               "title": "License"
            },
            "source": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The source from which this full text was obtained.",
               "title": "Source"
            },
            "source_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The URL of the source from which this full text was obtained.",
               "title": "Source Url"
            },
            "retrieved_at": {
               "anyOf": [
                  {
                     "format": "date-time",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The timestamp when this full text was retrieved.",
               "title": "Retrieved At"
            }
         },
         "required": [
            "file_url"
         ],
         "title": "FullTextEnhancement",
         "type": "object"
      },
      "JsonValue": {},
      "LinkedDataEnhancement": {
         "description": "An enhancement for storing structured data in a linked data format.\n\nThe content is a JSON-LD document conforming to the vocabulary and\ncontext specified. This enhancement type is produced by mapping robots\nthat transform RawEnhancement data into the shared vocabulary.",
         "properties": {
            "enhancement_type": {
               "const": "linked_data",
               "default": "linked_data",
               "title": "Enhancement Type",
               "type": "string"
            },
            "vocabulary_uri": {
               "description": "The URI of the vocabulary against which this data was produced. Used for compatibility checking.",
               "examples": [
                  "https://vocab.evrepo.org/vocabulary/v1"
               ],
               "format": "uri",
               "maxLength": 2083,
               "minLength": 1,
               "title": "Vocabulary Uri",
               "type": "string"
            },
            "data": {
               "additionalProperties": {
                  "$ref": "#/$defs/JsonValue"
               },
               "description": "The JSON-LD content. Must contain an '@context' key with a valid URI string. When combined with the @context, this forms a complete linked data graph.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "vocabulary_uri",
            "data"
         ],
         "title": "LinkedDataEnhancement",
         "type": "object"
      },
      "Location": {
         "description": "A location where a reference can be found.\n\nThis maps almost completely to the OpenAlex\n[Location object](https://docs.openalex.org/api-entities/works/work-object/location-object)",
         "properties": {
            "is_oa": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): True if an Open Access (OA) version of this work is available\nat this location. May be left as null if this is unknown (and thus)\ntreated effectively as `false`.\n",
               "title": "Is Oa"
            },
            "version": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/DriverVersion"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\nThe version (according to the DRIVER versioning scheme) of this location.\n"
            },
            "landing_page_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "(From OpenAlex): The landing page URL for this location.",
               "title": "Landing Page Url"
            },
            "pdf_url": {
               "anyOf": [
                  {
                     "format": "uri",
                     "maxLength": 2083,
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): A URL where you can find this location as a PDF.\n",
               "title": "Pdf Url"
            },
            "license": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "\n(From OpenAlex): The location's publishing license. This can be a Creative\nCommons license such as cc0 or cc-by, a publisher-specific license, or null\nwhich means we are not able to determine a license for this location.\n",
               "title": "License"
            },
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Any extra metadata about this location",
               "title": "Extra"
            }
         },
         "title": "Location",
         "type": "object"
      },
      "LocationEnhancement": {
         "description": "An enhancement which describes locations where this reference can be found.\n\nThis maps closely (almost exactly) to OpenAlex's locations.",
         "properties": {
            "enhancement_type": {
               "const": "location",
               "default": "location",
               "title": "Enhancement Type",
               "type": "string"
            },
            "locations": {
               "description": "A list of locations where this reference can be found.",
               "items": {
                  "$ref": "#/$defs/Location"
               },
               "minItems": 1,
               "title": "Locations",
               "type": "array"
            }
         },
         "required": [
            "locations"
         ],
         "title": "LocationEnhancement",
         "type": "object"
      },
      "OpenAlexIdentifier": {
         "description": "An external identifier representing an OpenAlex ID.",
         "properties": {
            "identifier": {
               "description": "The OpenAlex ID of the reference. Format: 'W' followed by digits. Example: W2741809807",
               "pattern": "^W\\d+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "open_alex",
               "default": "open_alex",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "OpenAlexIdentifier",
         "type": "object"
      },
      "OtherIdentifier": {
         "description": "An external identifier not otherwise defined by the repository.",
         "properties": {
            "identifier": {
               "description": "The identifier of the reference.",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "other",
               "default": "other",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            },
            "other_identifier_name": {
               "description": "The name of the undocumented identifier type.",
               "title": "Other Identifier Name",
               "type": "string"
            }
         },
         "required": [
            "identifier",
            "other_identifier_name"
         ],
         "title": "OtherIdentifier",
         "type": "object"
      },
      "Pagination": {
         "description": "Pagination information for journal articles.\n\nMaps to OpenAlex's work.biblio object. All fields are strings to match\nOpenAlex's format, which may include non-numeric values like \"Spring\" or \"A1\".",
         "properties": {
            "volume": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The volume number of the journal/publication.",
               "title": "Volume"
            },
            "issue": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The issue number of the journal/publication.",
               "title": "Issue"
            },
            "first_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The first page number of the reference in the publication.",
               "title": "First Page"
            },
            "last_page": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The last page number of the reference in the publication.",
               "title": "Last Page"
            }
         },
         "title": "Pagination",
         "type": "object"
      },
      "ProQuestIdentifier": {
         "description": "An external identifier representing a ProQuest ID.",
         "properties": {
            "identifier": {
               "description": "The ProQuest ID of the reference. Format: numeric digits only. Example: 12345678",
               "pattern": "[0-9]+$",
               "title": "Identifier",
               "type": "string"
            },
            "identifier_type": {
               "const": "pro_quest",
               "default": "pro_quest",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "ProQuestIdentifier",
         "type": "object"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID (PMID) of the reference. Example: 12345678",
               "exclusiveMinimum": 0,
               "title": "Identifier",
               "type": "integer"
            },
            "identifier_type": {
               "const": "pm_id",
               "default": "pm_id",
               "description": "The type of identifier used.",
               "title": "Identifier Type",
               "type": "string"
            }
         },
         "required": [
            "identifier"
         ],
         "title": "PubMedIdentifier",
         "type": "object"
      },
      "PublicationVenue": {
         "description": "A publication venue (journal, repository, conference, etc.).",
         "properties": {
            "display_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The display name of the venue (journal name, repository name, etc.)",
               "title": "Display Name"
            },
            "venue_type": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PublicationVenueType"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The type of venue: journal, repository, book, conference, etc."
            },
            "issn": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "List of ISSNs associated with this venue (print and electronic)",
               "title": "Issn"
            },
            "issn_l": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The linking ISSN - a canonical ISSN for the venue across format changes",
               "title": "Issn L"
            },
            "host_organization_name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Display name of the host organization (publisher)",
               "title": "Host Organization Name"
            }
         },
         "title": "PublicationVenue",
         "type": "object"
      },
      "PublicationVenueType": {
         "description": "Type of publication venue.\n\nAligns with OpenAlex source types.",
         "enum": [
            "journal",
            "repository",
            "conference",
            "ebook_platform",
            "book_series",
            "other"
         ],
         "title": "PublicationVenueType",
         "type": "string"
      },
      "RawEnhancement": {
         "description": "An enhancement for storing raw/arbitrary/unstructured data.\n\nData in these enhancements is intended for future conversion into structured form.\n\nThis enhancement accepts any fields passed in to `data`. These enhancements cannot\nbe created by robots.",
         "properties": {
            "enhancement_type": {
               "const": "raw",
               "default": "raw",
               "title": "Enhancement Type",
               "type": "string"
            },
            "source_export_date": {
               "description": "Date the enhancement data was retrieved.",
               "format": "date-time",
               "title": "Source Export Date",
               "type": "string"
            },
            "description": {
               "description": "Description of the data to aid in future refinement.",
               "title": "Description",
               "type": "string"
            },
            "metadata": {
               "additionalProperties": true,
               "description": "Additional metadata to aid in future structuring of raw data",
               "title": "Metadata",
               "type": "object"
            },
            "data": {
               "description": "Unstructured data for later processing.",
               "title": "Data"
            }
         },
         "required": [
            "source_export_date",
            "description",
            "data"
         ],
         "title": "RawEnhancement",
         "type": "object"
      },
      "ReferenceAssociationEnhancement": {
         "description": "An enhancement for storing associations between references.",
         "properties": {
            "enhancement_type": {
               "const": "reference_association",
               "default": "reference_association",
               "title": "Enhancement Type",
               "type": "string"
            },
            "associated_reference_ids": {
               "description": "A list of Identifiers which are associated to this reference. These can either be ExternalIdentifiers or resolved repository UUID4s.",
               "items": {
                  "anyOf": [
                     {
                        "discriminator": {
                           "mapping": {
                              "doi": "#/$defs/DOIIdentifier",
                              "eric": "#/$defs/ERICIdentifier",
                              "open_alex": "#/$defs/OpenAlexIdentifier",
                              "other": "#/$defs/OtherIdentifier",
                              "pm_id": "#/$defs/PubMedIdentifier",
                              "pro_quest": "#/$defs/ProQuestIdentifier"
                           },
                           "propertyName": "identifier_type"
                        },
                        "oneOf": [
                           {
                              "$ref": "#/$defs/DOIIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ERICIdentifier"
                           },
                           {
                              "$ref": "#/$defs/PubMedIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ProQuestIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OpenAlexIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OtherIdentifier"
                           }
                        ]
                     },
                     {
                        "anyOf": [
                           {
                              "format": "uuid4",
                              "type": "string"
                           },
                           {
                              "format": "uuid7",
                              "type": "string"
                           }
                        ],
                        "description": "A DESTINY UUID, which can be either UUID4 or UUID7."
                     }
                  ]
               },
               "minItems": 1,
               "title": "Associated Reference Ids",
               "type": "array"
            },
            "association_type": {
               "$ref": "#/$defs/ReferenceAssociationType",
               "description": "The type of association between this reference and the associated ones. Direction is important: \"this reference <association_type> associated reference\"."
            }
         },
         "required": [
            "associated_reference_ids",
            "association_type"
         ],
         "title": "ReferenceAssociationEnhancement",
         "type": "object"
      },
      "ReferenceAssociationType": {
         "description": "The type of association between references.\n\nDirection is important: \"this reference <association_type> associated reference\".",
         "enum": [
            "cites",
            "is_cited_by",
            "is_similar_to"
         ],
         "title": "ReferenceAssociationType",
         "type": "string"
      },
      "ReferenceFileInput": {
         "description": "Enhancement model used to marshall a file input.",
         "properties": {
            "visibility": {
               "$ref": "#/$defs/Visibility",
               "default": "public",
               "description": "The level of visibility of the reference"
            },
            "identifiers": {
               "anyOf": [
                  {
                     "items": {
                        "discriminator": {
                           "mapping": {
                              "doi": "#/$defs/DOIIdentifier",
                              "eric": "#/$defs/ERICIdentifier",
                              "open_alex": "#/$defs/OpenAlexIdentifier",
                              "other": "#/$defs/OtherIdentifier",
                              "pm_id": "#/$defs/PubMedIdentifier",
                              "pro_quest": "#/$defs/ProQuestIdentifier"
                           },
                           "propertyName": "identifier_type"
                        },
                        "oneOf": [
                           {
                              "$ref": "#/$defs/DOIIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ERICIdentifier"
                           },
                           {
                              "$ref": "#/$defs/PubMedIdentifier"
                           },
                           {
                              "$ref": "#/$defs/ProQuestIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OpenAlexIdentifier"
                           },
                           {
                              "$ref": "#/$defs/OtherIdentifier"
                           }
                        ]
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of `ExternalIdentifiers` for the Reference",
               "title": "Identifiers"
            },
            "enhancements": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/EnhancementFileInput"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A list of enhancements for the reference",
               "title": "Enhancements"
            }
         },
         "title": "ReferenceFileInput",
         "type": "object"
      },
      "ScoreAnnotation": {
         "description": "An annotation which represents the score for a label.\n\nThis is similar to a BooleanAnnotation, but lacks a boolean determination\nas to the application of the label.",
         "properties": {
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "pattern": "^[^/]+$",
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "type": "string"
            },
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "score": {
               "description": "Score for this annotation",
               "title": "Score",
               "type": "number"
            },
            "data": {
               "additionalProperties": true,
               "description": "An object representation of the annotation including any confidence scores or descriptions.",
               "title": "Data",
               "type": "object"
            }
         },
         "required": [
            "scheme",
            "label",
            "score"
         ],
         "title": "ScoreAnnotation",
         "type": "object"
      },
      "Visibility": {
         "description": "The visibility of a data element in the repository.\n\nThis is used to manage whether information should be publicly available or\nrestricted (generally due to copyright constraints from publishers).",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   }
}

Fields:

• duplicate_decision_id (uuid.UUID | None)

• errors (list[str])

• reference (destiny_sdk.references.ReferenceFileInput | None)

• reference_id (uuid.UUID | None)

field duplicate_decision_id: Annotated[Annotated[UUID, UuidVersion(uuid_version=4)] | Annotated[UUID, UuidVersion(uuid_version=7)], FieldInfo(annotation=NoneType, required=True, description='A DESTINY UUID, which can be either UUID4 or UUID7.')] | None = None

The ID of the pending duplicate decision, if required

field errors: list[str] [Optional]

A list of errors encountered during the creation process

field reference: ReferenceFileInput | None = None

The validated reference input.

field reference_id: Annotated[Annotated[UUID, UuidVersion(uuid_version=4)] | Annotated[UUID, UuidVersion(uuid_version=7)], FieldInfo(annotation=NoneType, required=True, description='A DESTINY UUID, which can be either UUID4 or UUID7.')] | None = None

The ID of the created reference, if created

classmethod from_raw(record_str: str, entry_ref: int) → Self

Parse a reference file input from a string and validate it.

property error_str: str | None

Return a string of errors if they exist.

pydantic model app.domain.references.models.validators.ReferenceFileInputValidator

Validator for the top-level schema of a reference entry from a file.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ReferenceFileInputValidator",
   "description": "Validator for the top-level schema of a reference entry from a file.",
   "type": "object",
   "properties": {
      "visibility": {
         "$ref": "#/$defs/Visibility",
         "default": "public",
         "description": "The level of visibility of the reference"
      },
      "identifiers": {
         "items": {
            "$ref": "#/$defs/JSON"
         },
         "minItems": 1,
         "title": "Identifiers",
         "type": "array"
      },
      "enhancements": {
         "items": {
            "$ref": "#/$defs/JSON"
         },
         "title": "Enhancements",
         "type": "array"
      }
   },
   "$defs": {
      "JSON": {
         "anyOf": [
            {
               "additionalProperties": {
                  "$ref": "#/$defs/JSON"
               },
               "type": "object"
            },
            {
               "items": {
                  "$ref": "#/$defs/JSON"
               },
               "type": "array"
            },
            {
               "type": "string"
            },
            {
               "type": "integer"
            },
            {
               "type": "number"
            },
            {
               "type": "boolean"
            },
            {
               "type": "null"
            }
         ]
      },
      "Visibility": {
         "description": "The visibility of a data element in the repository.\n\nThis is used to manage whether information should be publicly available or\nrestricted (generally due to copyright constraints from publishers).\n\nTODO: Implement data governance layer to manage this.",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   },
   "additionalProperties": false,
   "required": [
      "identifiers"
   ]
}

Config:

• extra: str = forbid

Fields:

• enhancements (list[JSON])

• identifiers (list[JSON])

• visibility (app.domain.references.models.models.Visibility)

field enhancements: list[JSON] [Optional]

field identifiers: list[JSON] [Required]

Constraints:

• min_length = 1

field visibility: Visibility = Visibility.PUBLIC

The level of visibility of the reference

app.domain.references.models.validators.parse_identifier_lookup_from_string(identifier_lookup_string: str, delimiter: str = ':') → IdentifierLookup

Parse an identifier lookup string into an IdentifierLookup object.