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.CandidateCanonicalSearchFields

Projection representing fields used for candidate canonical selection.

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. The search implementation lives at app.domain.references.repository.ReferenceESRepository.search_for_candidate_canonicals.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "CandidateCanonicalSearchFields",
   "description": "Projection representing fields used for candidate canonical selection.\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. The search implementation lives at\n:attr:`app.domain.references.repository.ReferenceESRepository.search_for_candidate_canonicals`.",
   "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.

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 chain of duplicates longer than allowed.

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.",
               "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"
            },
            "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"
            }
         },
         "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": {
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of the annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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.",
               "pattern": "^10\\.\\d{4,9}/[-._;()/:a-zA-Z0-9%<>\\[\\]+&]+$",
               "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"
      },
      "Enhancement": {
         "description": "Core enhancement model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "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",
                     "location": "#/$defs/LocationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  }
               ],
               "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"
      },
      "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",
                     "open_alex": "#/$defs/OpenAlexIdentifier",
                     "other": "#/$defs/OtherIdentifier",
                     "pm_id": "#/$defs/PubMedIdentifier"
                  },
                  "propertyName": "identifier_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/DOIIdentifier"
                  },
                  {
                     "$ref": "#/$defs/PubMedIdentifier"
                  },
                  {
                     "$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.",
               "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"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID of the reference.",
               "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"
      },
      "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"
      },
      "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": "uuid4",
               "title": "Reference Id",
               "type": "string"
            },
            "enhancement_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "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": "uuid4",
                  "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": "uuid4",
                     "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": {
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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)

• 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)

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

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

The content of the enhancement.

field derived_from: list[UUID] | None = None

List of enhancement IDs that this enhancement was derived from.

field id: uuid.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 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, excluding relationships.

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 Azure Blob Storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in Azure Blob Storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in Azure Blob Storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio"
         ],
         "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": "uuid4",
               "title": "Reference Id",
               "type": "string"
            },
            "robot_id": {
               "description": "The ID of the robot that will perform the enhancement.",
               "format": "uuid4",
               "title": "Robot Id",
               "type": "string"
            },
            "enhancement_request_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "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": "uuid4",
                     "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"
            }
         },
         "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- `accepted`: Enhancement has been accepted for processing.\n- `importing`: Enhancement is currently being imported.\n- `indexing`: Enhancement is currently being indexed.\n- `indexing_failed`: Enhancement indexing has failed.\n- `completed`: Enhancement has been processed successfully.\n- `failed`: Enhancement processing has failed.",
         "enum": [
            "pending",
            "accepted",
            "importing",
            "indexing",
            "indexing_failed",
            "completed",
            "failed"
         ],
         "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.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.ExternalIdentifierSearch

Model to search for an external identifier.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "ExternalIdentifierSearch",
   "description": "Model to search for an external identifier.",
   "type": "object",
   "properties": {
      "identifier": {
         "description": "The identifier itself.",
         "title": "Identifier",
         "type": "string"
      },
      "identifier_type": {
         "$ref": "#/$defs/ExternalIdentifierType",
         "description": "The type of the identifier."
      },
      "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",
            "pm_id",
            "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.

field other_identifier_name: str | None = None

The name of the other identifier.

classmethod from_specific(external_identifier: Annotated[DOIIdentifier | PubMedIdentifier | 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.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": {
         "$ref": "#/$defs/ExternalIdentifierType",
         "description": "The type of the identifier."
      },
      "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",
            "pm_id",
            "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.

field other_identifier_name: str | None = None

The name of the other identifier.

classmethod from_specific(external_identifier: Annotated[DOIIdentifier | PubMedIdentifier | 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.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.",
               "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"
            },
            "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"
            }
         },
         "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": {
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of the annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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.",
               "pattern": "^10\\.\\d{4,9}/[-._;()/:a-zA-Z0-9%<>\\[\\]+&]+$",
               "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"
      },
      "Enhancement": {
         "description": "Core enhancement model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "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",
                     "location": "#/$defs/LocationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  }
               ],
               "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"
      },
      "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",
                     "open_alex": "#/$defs/OpenAlexIdentifier",
                     "other": "#/$defs/OtherIdentifier",
                     "pm_id": "#/$defs/PubMedIdentifier"
                  },
                  "propertyName": "identifier_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/DOIIdentifier"
                  },
                  {
                     "$ref": "#/$defs/PubMedIdentifier"
                  },
                  {
                     "$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.",
               "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"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID of the reference.",
               "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"
      },
      "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"
      },
      "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": "uuid4",
               "title": "Reference Id",
               "type": "string"
            },
            "enhancement_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "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": "uuid4",
                  "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": "uuid4",
                     "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": {
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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.PubMedIdentifier | destiny_sdk.identifiers.OpenAlexIdentifier | destiny_sdk.identifiers.OtherIdentifier)

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

• reference_id (uuid.UUID)

field id: uuid.UUID [Optional]

The autogenerated database ID.

field identifier: Annotated[DOIIdentifier | PubMedIdentifier | 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": "uuid4",
         "title": "Reference Id",
         "type": "string"
      },
      "robot_id": {
         "description": "The ID of the robot that will perform the enhancement.",
         "format": "uuid4",
         "title": "Robot Id",
         "type": "string"
      },
      "enhancement_request_id": {
         "anyOf": [
            {
               "format": "uuid4",
               "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": "uuid4",
               "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"
      }
   },
   "$defs": {
      "PendingEnhancementStatus": {
         "description": "The status of a pending enhancement.\n\n**Allowed values**:\n- `pending`: Enhancement is waiting to be processed.\n- `accepted`: Enhancement has been accepted for processing.\n- `importing`: Enhancement is currently being imported.\n- `indexing`: Enhancement is currently being indexed.\n- `indexing_failed`: Enhancement indexing has failed.\n- `completed`: Enhancement has been processed successfully.\n- `failed`: Enhancement processing has failed.",
         "enum": [
            "pending",
            "accepted",
            "importing",
            "indexing",
            "indexing_failed",
            "completed",
            "failed"
         ],
         "title": "PendingEnhancementStatus",
         "type": "string"
      }
   },
   "required": [
      "reference_id",
      "robot_id"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• enhancement_request_id (uuid.UUID | None)

• id (uuid.UUID)

• reference_id (uuid.UUID)

• 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

field enhancement_request_id: Annotated[UUID, UuidVersion(uuid_version=4)] | None = None

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

Validated by:

• check_enhancement_request_or_source_present

field id: uuid.UUID [Optional]

The autogenerated database ID.

Validated by:

• check_enhancement_request_or_source_present

field reference_id: Annotated[UUID, UuidVersion(uuid_version=4)] [Required]

The ID of the reference to be enhanced.

Constraints:

• uuid_version = 4

Validated by:

• check_enhancement_request_or_source_present

field robot_enhancement_batch_id: Annotated[UUID, UuidVersion(uuid_version=4)] | 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: Annotated[UUID, UuidVersion(uuid_version=4)] [Required]

The ID of the robot that will perform the enhancement.

Constraints:

• uuid_version = 4

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 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. - accepted: Enhancement has been accepted for processing. - importing: Enhancement is currently being imported. - indexing: Enhancement is currently being indexed. - indexing_failed: Enhancement indexing has failed. - completed: Enhancement has been processed successfully. - failed: Enhancement processing has failed.

ACCEPTED = 'accepted'

COMPLETED = 'completed'

FAILED = 'failed'

IMPORTING = 'importing'

INDEXING = 'indexing'

INDEXING_FAILED = 'indexing_failed'

PENDING = 'pending'

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.",
               "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"
            },
            "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"
            }
         },
         "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": {
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of the annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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.",
               "pattern": "^10\\.\\d{4,9}/[-._;()/:a-zA-Z0-9%<>\\[\\]+&]+$",
               "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"
      },
      "Enhancement": {
         "description": "Core enhancement model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "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",
                     "location": "#/$defs/LocationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  }
               ],
               "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"
      },
      "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",
                     "open_alex": "#/$defs/OpenAlexIdentifier",
                     "other": "#/$defs/OtherIdentifier",
                     "pm_id": "#/$defs/PubMedIdentifier"
                  },
                  "propertyName": "identifier_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/DOIIdentifier"
                  },
                  {
                     "$ref": "#/$defs/PubMedIdentifier"
                  },
                  {
                     "$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.",
               "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"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID of the reference.",
               "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"
      },
      "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"
      },
      "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": "uuid4",
               "title": "Reference Id",
               "type": "string"
            },
            "enhancement_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "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": "uuid4",
                  "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": "uuid4",
                     "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": {
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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.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 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 canonical_chain_length: int

Get the length of the canonical chain for this reference.

This is the number of references in the chain from this reference to the root canonical reference, including this reference.

Requires canonical_reference to be preloaded, will always return 1 if not.

property 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": "uuid4",
         "title": "Reference Id",
         "type": "string"
      },
      "enhancement_id": {
         "anyOf": [
            {
               "format": "uuid4",
               "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": "uuid4",
            "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": "uuid4",
               "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[Annotated[UUID, UuidVersion(uuid_version=4)]] [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: Annotated[UUID, UuidVersion(uuid_version=4)] | 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: Annotated[UUID, UuidVersion(uuid_version=4)] | 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.UUID [Optional]

The autogenerated database ID.

Validated by:

• check_active_decision_is_terminal

• check_canonical_reference_id_populated_iff_duplicate

field reference_id: Annotated[UUID, UuidVersion(uuid_version=4)] [Required]

The ID of the reference being evaluated.

Constraints:

• uuid_version = 4

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": "uuid4",
               "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_canonical » all fields

field canonical_reference_id: Annotated[UUID, UuidVersion(uuid_version=4)] | None = None

The ID of the determined canonical reference.

Validated by:

• check_canonical_reference_id_populated_iff_canonical

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_canonical

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

Validated by:

• check_canonical_reference_id_populated_iff_canonical

validator check_canonical_reference_id_populated_iff_canonical  »  all fields

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

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": "uuid4",
            "type": "string"
         },
         "title": "Reference Ids",
         "type": "array"
      }
   },
   "required": [
      "reference_ids"
   ]
}

Fields:

• reference_ids (list[uuid.UUID])

field reference_ids: list[Annotated[UUID, UuidVersion(uuid_version=4)]] [Required]

A list of reference IDs.

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.",
               "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"
            },
            "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"
            }
         },
         "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": {
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of the annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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.",
               "pattern": "^10\\.\\d{4,9}/[-._;()/:a-zA-Z0-9%<>\\[\\]+&]+$",
               "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"
      },
      "Enhancement": {
         "description": "Core enhancement model with database attributes included.",
         "properties": {
            "id": {
               "description": "The autogenerated database ID.",
               "format": "uuid",
               "title": "Id",
               "type": "string"
            },
            "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",
                     "location": "#/$defs/LocationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  }
               ],
               "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"
      },
      "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",
                     "open_alex": "#/$defs/OpenAlexIdentifier",
                     "other": "#/$defs/OtherIdentifier",
                     "pm_id": "#/$defs/PubMedIdentifier"
                  },
                  "propertyName": "identifier_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/DOIIdentifier"
                  },
                  {
                     "$ref": "#/$defs/PubMedIdentifier"
                  },
                  {
                     "$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.",
               "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"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID of the reference.",
               "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"
      },
      "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"
      },
      "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": "uuid4",
               "title": "Reference Id",
               "type": "string"
            },
            "enhancement_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "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": "uuid4",
                  "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": "uuid4",
                     "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": {
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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.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 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 canonical_chain_length: int

Get the length of the canonical chain for this reference.

This is the number of references in the chain from this reference to the root canonical reference, including this reference.

Requires canonical_reference to be preloaded, will always return 1 if not.

property 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.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": "uuid4",
         "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.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: Annotated[UUID, UuidVersion(uuid_version=4)] [Required]

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

Constraints:

• uuid_version = 4

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": "uuid4",
         "title": "Robot Id",
         "type": "string"
      },
      "reference_ids": {
         "items": {
            "format": "uuid4",
            "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[Annotated[UUID, UuidVersion(uuid_version=4)]] [Required]

field robot_id: Annotated[UUID, UuidVersion(uuid_version=4)] [Required]

Constraints:

• uuid_version = 4

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": "uuid4",
         "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 Azure Blob Storage.",
               "pattern": "^[^/]*$",
               "title": "Container",
               "type": "string"
            },
            "path": {
               "description": "The path to the file in Azure Blob Storage.",
               "title": "Path",
               "type": "string"
            },
            "filename": {
               "description": "The name of the file in Azure Blob Storage.",
               "pattern": "^[^/]*$",
               "title": "Filename",
               "type": "string"
            }
         },
         "required": [
            "location",
            "container",
            "path",
            "filename"
         ],
         "title": "BlobStorageFile",
         "type": "object"
      },
      "BlobStorageLocation": {
         "description": "Blob Storage locations.",
         "enum": [
            "azure",
            "minio"
         ],
         "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": "uuid4",
               "title": "Reference Id",
               "type": "string"
            },
            "robot_id": {
               "description": "The ID of the robot that will perform the enhancement.",
               "format": "uuid4",
               "title": "Robot Id",
               "type": "string"
            },
            "enhancement_request_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "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": "uuid4",
                     "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"
            }
         },
         "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- `accepted`: Enhancement has been accepted for processing.\n- `importing`: Enhancement is currently being imported.\n- `indexing`: Enhancement is currently being indexed.\n- `indexing_failed`: Enhancement indexing has failed.\n- `completed`: Enhancement has been processed successfully.\n- `failed`: Enhancement processing has failed.",
         "enum": [
            "pending",
            "accepted",
            "importing",
            "indexing",
            "indexing_failed",
            "completed",
            "failed"
         ],
         "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.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: Annotated[UUID, UuidVersion(uuid_version=4)] [Required]

The ID of the robot that will perform the enhancement.

Constraints:

• uuid_version = 4

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.

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 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.",
               "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"
            },
            "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"
            }
         },
         "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": {
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of the annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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"
      },
      "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"
      },
      "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",
                     "location": "#/$defs/LocationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  }
               ],
               "title": "Content"
            }
         },
         "required": [
            "source",
            "visibility",
            "content"
         ],
         "title": "EnhancementFileInput",
         "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"
      },
      "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": {
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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.",
               "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"
            },
            "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"
            }
         },
         "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": {
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of the annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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"
      },
      "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"
      },
      "Enhancement": {
         "description": "Core enhancement class.",
         "properties": {
            "id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ID of the enhancement. Populated by the repository when sending enhancements with references.",
               "title": "Id"
            },
            "reference_id": {
               "description": "The ID of the reference this enhancement is associated with.",
               "format": "uuid4",
               "title": "Reference Id",
               "type": "string"
            },
            "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": "uuid4",
                        "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",
                     "location": "#/$defs/LocationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  }
               ],
               "title": "Content"
            }
         },
         "required": [
            "reference_id",
            "source",
            "visibility",
            "content"
         ],
         "title": "Enhancement",
         "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": {
               "description": "The ID of the reference which caused the error.",
               "format": "uuid4",
               "title": "Reference Id",
               "type": "string"
            }
         },
         "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"
      },
      "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": {
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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",
                     "open_alex": "#/$defs/OpenAlexIdentifier",
                     "other": "#/$defs/OtherIdentifier",
                     "pm_id": "#/$defs/PubMedIdentifier"
                  },
                  "propertyName": "identifier_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/DOIIdentifier"
                  },
                  {
                     "$ref": "#/$defs/PubMedIdentifier"
                  },
                  {
                     "$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.",
               "pattern": "^10\\.\\d{4,9}/[-._;()/:a-zA-Z0-9%<>\\[\\]+&]+$",
               "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"
      },
      "OpenAlexIdentifier": {
         "description": "An external identifier representing an OpenAlex ID.",
         "properties": {
            "identifier": {
               "description": "The OpenAlex ID of the reference.",
               "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"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID of the reference.",
               "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.PubMedIdentifier | 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 | PubMedIdentifier | 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": [
            {
               "format": "uuid4",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The ID of the created reference, if created",
         "title": "Reference Id"
      },
      "duplicate_decision_id": {
         "anyOf": [
            {
               "format": "uuid4",
               "type": "string"
            },
            {
               "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.",
               "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"
            },
            "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"
            }
         },
         "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": {
            "annotation_type": {
               "const": "boolean",
               "default": "boolean",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of the annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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.",
               "pattern": "^10\\.\\d{4,9}/[-._;()/:a-zA-Z0-9%<>\\[\\]+&]+$",
               "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"
      },
      "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",
                     "location": "#/$defs/LocationEnhancement"
                  },
                  "propertyName": "enhancement_type"
               },
               "oneOf": [
                  {
                     "$ref": "#/$defs/BibliographicMetadataEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AbstractContentEnhancement"
                  },
                  {
                     "$ref": "#/$defs/AnnotationEnhancement"
                  },
                  {
                     "$ref": "#/$defs/LocationEnhancement"
                  }
               ],
               "title": "Content"
            }
         },
         "required": [
            "source",
            "visibility",
            "content"
         ],
         "title": "EnhancementFileInput",
         "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.",
               "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"
      },
      "PubMedIdentifier": {
         "description": "An external identifier representing a PubMed ID.",
         "properties": {
            "identifier": {
               "description": "The PubMed ID of the reference.",
               "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"
      },
      "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",
                              "open_alex": "#/$defs/OpenAlexIdentifier",
                              "other": "#/$defs/OtherIdentifier",
                              "pm_id": "#/$defs/PubMedIdentifier"
                           },
                           "propertyName": "identifier_type"
                        },
                        "oneOf": [
                           {
                              "$ref": "#/$defs/DOIIdentifier"
                           },
                           {
                              "$ref": "#/$defs/PubMedIdentifier"
                           },
                           {
                              "$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": {
            "annotation_type": {
               "const": "score",
               "default": "score",
               "title": "Annotation Type",
               "type": "string"
            },
            "scheme": {
               "description": "An identifier for the scheme of annotation",
               "examples": [
                  "openalex:topic",
                  "pubmed:mesh"
               ],
               "title": "Scheme",
               "type": "string"
            },
            "label": {
               "description": "A high level label for this annotation like the name of the topic",
               "title": "Label",
               "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[UUID, UuidVersion(uuid_version=4)] | 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[UUID, UuidVersion(uuid_version=4)] | 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