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

Request to add enhancements to a list of references.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "BatchEnhancementRequest",
   "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/BatchEnhancementRequestStatus",
         "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."
      }
   },
   "$defs": {
      "BatchEnhancementRequestStatus": {
         "description": "The status of an enhancement request.\n\n**Allowed values**:\n- `received`: Enhancement request has been received by the repo.\n- `accepted`: Enhancement request has been accepted by the robot.\n- `rejected`: Enhancement request has been rejected by the robot.\n- `partial_failed`: Some enhancements failed to create.\n- `failed`: All enhancements failed to create.\n- `importing`: Enhancements have been received by the repo and are being imported.\n- `indexing`: Enhancements have been imported and are being indexed.\n- `indexing_failed`: Enhancements have been imported but indexing failed.\n- `completed`: All enhancements have been created.",
         "enum": [
            "received",
            "accepted",
            "rejected",
            "partial_failed",
            "failed",
            "importing",
            "indexing",
            "indexing_failed",
            "completed"
         ],
         "title": "BatchEnhancementRequestStatus",
         "type": "string"
      },
      "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"
      }
   },
   "required": [
      "reference_ids",
      "robot_id"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• enhancement_parameters (dict | None)

• error (str | None)

• id (uuid.UUID)

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

• reference_ids (list[uuid.UUID])

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

• 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 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: BatchEnhancementRequestStatus = BatchEnhancementRequestStatus.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.

async classmethod from_sdk(enhancement_request: BatchEnhancementRequestIn) → Self

Create an enhancement request from the SDK model.

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.

async to_batch_robot_request_sdk(to_signed_url: Callable[[BlobStorageFile, BlobSignedUrlType], Awaitable[HttpUrl]]) → BatchRobotRequest

Convert the enhancement request to the SDK robot request model.

async to_sdk(to_signed_url: Callable[[BlobStorageFile, BlobSignedUrlType], Awaitable[HttpUrl]]) → BatchEnhancementRequestRead

Convert the enhancement request to the SDK model.

property n_references: int

The number of references in the request.

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

The status of an enhancement request.

Allowed values: - received: Enhancement request has been received by the repo. - accepted: Enhancement request has been accepted by the robot. - rejected: Enhancement request has been rejected by the robot. - partial_failed: Some enhancements failed to create. - failed: All enhancements failed to create. - importing: Enhancements have been received by the repo and are being imported. - indexing: Enhancements have been imported and are being indexed. - indexing_failed: Enhancements have been imported but indexing failed. - completed: All enhancements have been created.

ACCEPTED = 'accepted'

COMPLETED = 'completed'

FAILED = 'failed'

IMPORTING = 'importing'

INDEXING = 'indexing'

INDEXING_FAILED = 'indexing_failed'

PARTIAL_FAILED = 'partial_failed'

RECEIVED = 'received'

REJECTED = 'rejected'

pydantic model app.domain.references.models.models.BatchRobotResultValidationEntry

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

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "BatchRobotResultValidationEntry",
   "description": "A single entry in the validation result file for a batch 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 BatchEnhancementResultEntry 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 BatchEnhancementResultEntry 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.

async to_sdk() → BatchRobotResultValidationEntry

Convert the validation entry to the SDK model.

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",
               "description": "The process used to acquire the abstract."
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquyire the abstract.\n\n**Allowed values**:\n- `uninverted`\n- `closed_api`\n- `other`",
         "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"
                     }
                  ]
               },
               "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.\n\n**Allowed values**:\n- `first`: The first author.\n- `middle`: Any middle author\n- `last`: The last author",
         "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": {
               "description": "The ORCid of the author.",
               "title": "Orcid",
               "type": "string"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "orcid",
            "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)\n\nAllowed values:\n- `publishedVersion`: The document's version of record. This is the most\nauthoritative version.\n- `acceptedVersion`: The document after having completed peer review and being\nofficially accepted for publication. It will lack publisher formatting, but the\ncontent should be interchangeable with the that of the publishedVersion.\n- `submittedVersion`: the document as submitted to the publisher by the authors, but\nbefore peer-review. Its content may differ significantly from that of the accepted\narticle.",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "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"
               },
               "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"
            }
         },
         "title": "Reference",
         "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.\n\n**Allowed values**:\n\n- `public`: Visible to the general public without authentication.\n- `restricted`: Requires authentication to be visible.\n- `hidden`: Is not visible, but may be passed to data mining processes.",
         "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

async classmethod from_sdk(enhancement: Enhancement, reference_id: UUID | None = None) → Self

Create an enhancement from the SDK model.

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.

async to_sdk() → Enhancement

Convert the enhancement to the SDK model.

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

Request to add an enhancement to a specific reference.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "EnhancementRequest",
   "description": "Request to add an enhancement to a specific reference.",
   "type": "object",
   "properties": {
      "id": {
         "description": "The autogenerated database ID.",
         "format": "uuid",
         "title": "Id",
         "type": "string"
      },
      "reference_id": {
         "description": "The ID of the reference this enhancement is associated with.",
         "format": "uuid",
         "title": "Reference Id",
         "type": "string"
      },
      "robot_id": {
         "description": "The robot to request the enhancement from.",
         "format": "uuid",
         "title": "Robot Id",
         "type": "string"
      },
      "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"
      },
      "request_status": {
         "$ref": "#/$defs/EnhancementRequestStatus",
         "default": "received",
         "description": "The status of the request to create an enhancement."
      },
      "error": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Error encountered during the enhancement process.",
         "title": "Error"
      },
      "reference": {
         "anyOf": [
            {
               "$ref": "#/$defs/Reference"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The reference this enhancement is associated with."
      }
   },
   "$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",
               "description": "The process used to acquire the abstract."
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquyire the abstract.\n\n**Allowed values**:\n- `uninverted`\n- `closed_api`\n- `other`",
         "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"
                     }
                  ]
               },
               "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.\n\n**Allowed values**:\n- `first`: The first author.\n- `middle`: Any middle author\n- `last`: The last author",
         "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": {
               "description": "The ORCid of the author.",
               "title": "Orcid",
               "type": "string"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "orcid",
            "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)\n\nAllowed values:\n- `publishedVersion`: The document's version of record. This is the most\nauthoritative version.\n- `acceptedVersion`: The document after having completed peer review and being\nofficially accepted for publication. It will lack publisher formatting, but the\ncontent should be interchangeable with the that of the publishedVersion.\n- `submittedVersion`: the document as submitted to the publisher by the authors, but\nbefore peer-review. Its content may differ significantly from that of the accepted\narticle.",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "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"
      },
      "EnhancementRequestStatus": {
         "description": "The status of an enhancement request.\n\n**Allowed values**:\n- `received`: Enhancement request has been received.\n- `accepted`: Enhancement request has been accepted.\n- `rejected`: Enhancement request has been rejected.\n- `failed`: Enhancement failed to create.\n- `completed`: Enhancement has been created.",
         "enum": [
            "received",
            "accepted",
            "rejected",
            "failed",
            "completed"
         ],
         "title": "EnhancementRequestStatus",
         "type": "string"
      },
      "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"
               },
               "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"
            }
         },
         "title": "Reference",
         "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.\n\n**Allowed values**:\n\n- `public`: Visible to the general public without authentication.\n- `restricted`: Requires authentication to be visible.\n- `hidden`: Is not visible, but may be passed to data mining processes.",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   },
   "required": [
      "reference_id",
      "robot_id"
   ]
}

Config:

• from_attributes: bool = True

Fields:

• enhancement_parameters (dict | None)

• error (str | None)

• id (uuid.UUID)

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

• reference_id (uuid.UUID)

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

• robot_id (uuid.UUID)

• source (str | None)

field enhancement_parameters: dict | None = None

Additional optional parameters to pass through to the robot.

field error: str | None = None

Error encountered during the enhancement process.

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 request_status: EnhancementRequestStatus = EnhancementRequestStatus.RECEIVED

The status of the request to create an enhancement.

field robot_id: UUID [Required]

The robot to request the enhancement from.

field source: str | None = None

The source of the batch enhancement request.

async classmethod from_sdk(enhancement_request: EnhancementRequestIn) → Self

Create an enhancement request from the SDK model.

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.

async to_sdk() → EnhancementRequestRead

Convert the enhancement request to the SDK model.

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

The status of an enhancement request.

Allowed values: - received: Enhancement request has been received. - accepted: Enhancement request has been accepted. - rejected: Enhancement request has been rejected. - failed: Enhancement failed to create. - completed: Enhancement has been created.

ACCEPTED = 'accepted'

COMPLETED = 'completed'

FAILED = 'failed'

RECEIVED = 'received'

REJECTED = 'rejected'

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.\n**Allowed values**:\n- `doi`: A DOI (Digital Object Identifier) which is a unique identifier for a\ndocument.\n- `pmid`: A PubMed ID which is a unique identifier for a document in PubMed.\n- `openalex`: An OpenAlex ID which is a unique identifier for a document in\nOpenAlex.\n- `other`: Any other identifier not defined. This should be used sparingly.",
         "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.

async 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.\n**Allowed values**:\n- `doi`: A DOI (Digital Object Identifier) which is a unique identifier for a\ndocument.\n- `pmid`: A PubMed ID which is a unique identifier for a document in PubMed.\n- `openalex`: An OpenAlex ID which is a unique identifier for a document in\nOpenAlex.\n- `other`: Any other identifier not defined. This should be used sparingly.",
         "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.

async 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",
               "description": "The process used to acquire the abstract."
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquyire the abstract.\n\n**Allowed values**:\n- `uninverted`\n- `closed_api`\n- `other`",
         "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"
                     }
                  ]
               },
               "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.\n\n**Allowed values**:\n- `first`: The first author.\n- `middle`: Any middle author\n- `last`: The last author",
         "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": {
               "description": "The ORCid of the author.",
               "title": "Orcid",
               "type": "string"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "orcid",
            "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)\n\nAllowed values:\n- `publishedVersion`: The document's version of record. This is the most\nauthoritative version.\n- `acceptedVersion`: The document after having completed peer review and being\nofficially accepted for publication. It will lack publisher formatting, but the\ncontent should be interchangeable with the that of the publishedVersion.\n- `submittedVersion`: the document as submitted to the publisher by the authors, but\nbefore peer-review. Its content may differ significantly from that of the accepted\narticle.",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "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"
               },
               "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"
            }
         },
         "title": "Reference",
         "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.\n\n**Allowed values**:\n\n- `public`: Visible to the general public without authentication.\n- `restricted`: Requires authentication to be visible.\n- `hidden`: Is not visible, but may be passed to data mining processes.",
         "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.

async classmethod from_sdk(external_identifier: LinkedExternalIdentifier) → Self

Create an external identifier from the SDK model.

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.

async to_sdk() → LinkedExternalIdentifier

Convert the external identifier to the SDK model.

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",
               "description": "The process used to acquire the abstract."
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquyire the abstract.\n\n**Allowed values**:\n- `uninverted`\n- `closed_api`\n- `other`",
         "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"
                     }
                  ]
               },
               "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.\n\n**Allowed values**:\n- `first`: The first author.\n- `middle`: Any middle author\n- `last`: The last author",
         "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": {
               "description": "The ORCid of the author.",
               "title": "Orcid",
               "type": "string"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "orcid",
            "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)\n\nAllowed values:\n- `publishedVersion`: The document's version of record. This is the most\nauthoritative version.\n- `acceptedVersion`: The document after having completed peer review and being\nofficially accepted for publication. It will lack publisher formatting, but the\ncontent should be interchangeable with the that of the publishedVersion.\n- `submittedVersion`: the document as submitted to the publisher by the authors, but\nbefore peer-review. Its content may differ significantly from that of the accepted\narticle.",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "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"
               },
               "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"
            }
         },
         "title": "Reference",
         "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.\n\n**Allowed values**:\n\n- `public`: Visible to the general public without authentication.\n- `restricted`: Requires authentication to be visible.\n- `hidden`: Is not visible, but may be passed to data mining processes.",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   },
   "$ref": "#/$defs/Reference"
}

Config:

• from_attributes: bool = True

Fields:

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

async classmethod from_file_input(reference_in: ReferenceFileInput, reference_id: UUID | None = None) → Self

Create a reference including id hydration.

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.

async merge(incoming_reference: Self, collision_strategy: CollisionStrategy) → None

Merge an incoming reference into this one.

Args:

• existing_reference (Reference): The existing reference.

• incoming_reference (Reference): The incoming reference.

• collision_strategy (CollisionStrategy): The strategy to use for

  handling collisions.

Returns:

• Reference: The final reference to be persisted.

async to_sdk() → Reference

Convert the reference to the SDK model.

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

async classmethod from_sdk(data: RobotAutomationIn, robot_id: UUID) → Self

Create a RobotAutomation from the SDK input model.

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.

async to_sdk() → RobotAutomation

Convert the RobotAutomation to a RobotAutomation SDK model.

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

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.

Allowed values:

• public: Visible to the general public without authentication.

• restricted: Requires authentication to be visible.

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

HIDDEN = 'hidden'

PUBLIC = 'public'

RESTRICTED = 'restricted'

Pydantic models and adapters used to validate reference data.

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

Result of a batch enhancement request.

Show Entity Relationship Diagram

Show JSON schema

{
   "title": "BatchEnhancementResultValidator",
   "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",
               "description": "The process used to acquire the abstract."
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquyire the abstract.\n\n**Allowed values**:\n- `uninverted`\n- `closed_api`\n- `other`",
         "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"
                     }
                  ]
               },
               "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.\n\n**Allowed values**:\n- `first`: The first author.\n- `middle`: Any middle author\n- `last`: The last author",
         "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": {
               "description": "The ORCid of the author.",
               "title": "Orcid",
               "type": "string"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "orcid",
            "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)\n\nAllowed values:\n- `publishedVersion`: The document's version of record. This is the most\nauthoritative version.\n- `acceptedVersion`: The document after having completed peer review and being\nofficially accepted for publication. It will lack publisher formatting, but the\ncontent should be interchangeable with the that of the publishedVersion.\n- `submittedVersion`: the document as submitted to the publisher by the authors, but\nbefore peer-review. Its content may differ significantly from that of the accepted\narticle.",
         "enum": [
            "publishedVersion",
            "acceptedVersion",
            "submittedVersion",
            "other"
         ],
         "title": "DriverVersion",
         "type": "string"
      },
      "Enhancement": {
         "description": "Core enhancement class.",
         "properties": {
            "reference_id": {
               "description": "The ID of the reference this enhancement is associated with.",
               "format": "uuid",
               "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": "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"
            }
         },
         "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"
               },
               "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).\n\nTODO: Implement data governance layer to manage this.\n\n**Allowed values**:\n\n- `public`: Visible to the general public without authentication.\n- `restricted`: Requires authentication to be visible.\n- `hidden`: Is not visible, but may be passed to data mining processes.",
         "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

async classmethod from_raw(entry: str, entry_ref: int, expected_reference_ids: set[Annotated[UUID, UuidVersion(uuid_version=4)]]) → Self

Create a BatchEnhancementResult from a jsonl entry.

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",
               "description": "The process used to acquire the abstract."
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquyire the abstract.\n\n**Allowed values**:\n- `uninverted`\n- `closed_api`\n- `other`",
         "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"
                     }
                  ]
               },
               "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.\n\n**Allowed values**:\n- `first`: The first author.\n- `middle`: Any middle author\n- `last`: The last author",
         "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": {
               "description": "The ORCid of the author.",
               "title": "Orcid",
               "type": "string"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "orcid",
            "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)\n\nAllowed values:\n- `publishedVersion`: The document's version of record. This is the most\nauthoritative version.\n- `acceptedVersion`: The document after having completed peer review and being\nofficially accepted for publication. It will lack publisher formatting, but the\ncontent should be interchangeable with the that of the publishedVersion.\n- `submittedVersion`: the document as submitted to the publisher by the authors, but\nbefore peer-review. Its content may differ significantly from that of the accepted\narticle.",
         "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"
            },
            "enhancement_type": {
               "$ref": "#/$defs/EnhancementType",
               "description": "The type of 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",
            "enhancement_type",
            "content"
         ],
         "title": "EnhancementFileInput",
         "type": "object"
      },
      "EnhancementType": {
         "description": "The type of enhancement.\n\nThis is used to identify the type of enhancement in the `Enhancement` class.\n\n**Allowed values**:\n- `bibliographic`: Bibliographic metadata.\n- `abstract`: The abstract of a reference.\n- `annotation`: A free-form enhancement for tagging with labels.\n- `locations`: Locations where the reference can be found.\n- `full_text`: The full text of the reference. (To be implemeted)",
         "enum": [
            "bibliographic",
            "abstract",
            "annotation",
            "location",
            "full_text"
         ],
         "title": "EnhancementType",
         "type": "string"
      },
      "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"
               },
               "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).\n\nTODO: Implement data governance layer to manage this.\n\n**Allowed values**:\n\n- `public`: Visible to the general public without authentication.\n- `restricted`: Requires authentication to be visible.\n- `hidden`: Is not visible, but may be passed to data mining processes.",
         "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

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

Parse an enhancement from raw JSON.

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

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

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.",
   "type": "object",
   "properties": {
      "reference": {
         "anyOf": [
            {
               "$ref": "#/$defs/ReferenceFileInput"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "\n    The created reference.\n    If None, no reference was created.\n    "
      },
      "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"
      }
   },
   "$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",
               "description": "The process used to acquire the abstract."
            },
            "abstract": {
               "description": "The abstract of the reference.",
               "title": "Abstract",
               "type": "string"
            }
         },
         "required": [
            "process",
            "abstract"
         ],
         "title": "AbstractContentEnhancement",
         "type": "object"
      },
      "AbstractProcessType": {
         "description": "The process used to acquyire the abstract.\n\n**Allowed values**:\n- `uninverted`\n- `closed_api`\n- `other`",
         "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"
                     }
                  ]
               },
               "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.\n\n**Allowed values**:\n- `first`: The first author.\n- `middle`: Any middle author\n- `last`: The last author",
         "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": {
               "description": "The ORCid of the author.",
               "title": "Orcid",
               "type": "string"
            },
            "position": {
               "$ref": "#/$defs/AuthorPosition",
               "description": "The position of the author within the list of authors."
            }
         },
         "required": [
            "display_name",
            "orcid",
            "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)\n\nAllowed values:\n- `publishedVersion`: The document's version of record. This is the most\nauthoritative version.\n- `acceptedVersion`: The document after having completed peer review and being\nofficially accepted for publication. It will lack publisher formatting, but the\ncontent should be interchangeable with the that of the publishedVersion.\n- `submittedVersion`: the document as submitted to the publisher by the authors, but\nbefore peer-review. Its content may differ significantly from that of the accepted\narticle.",
         "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"
            },
            "enhancement_type": {
               "$ref": "#/$defs/EnhancementType",
               "description": "The type of 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",
            "enhancement_type",
            "content"
         ],
         "title": "EnhancementFileInput",
         "type": "object"
      },
      "EnhancementType": {
         "description": "The type of enhancement.\n\nThis is used to identify the type of enhancement in the `Enhancement` class.\n\n**Allowed values**:\n- `bibliographic`: Bibliographic metadata.\n- `abstract`: The abstract of a reference.\n- `annotation`: A free-form enhancement for tagging with labels.\n- `locations`: Locations where the reference can be found.\n- `full_text`: The full text of the reference. (To be implemeted)",
         "enum": [
            "bibliographic",
            "abstract",
            "annotation",
            "location",
            "full_text"
         ],
         "title": "EnhancementType",
         "type": "string"
      },
      "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"
               },
               "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).\n\nTODO: Implement data governance layer to manage this.\n\n**Allowed values**:\n\n- `public`: Visible to the general public without authentication.\n- `restricted`: Requires authentication to be visible.\n- `hidden`: Is not visible, but may be passed to data mining processes.",
         "enum": [
            "public",
            "restricted",
            "hidden"
         ],
         "title": "Visibility",
         "type": "string"
      }
   }
}

Fields:

• errors (list[str])

• reference (destiny_sdk.references.ReferenceFileInput | None)

• reference_id (uuid.UUID | None)

field errors: list[str] [Optional]

A list of errors encountered during the creation process

field reference: ReferenceFileInput | None = None

The created reference. If None, no reference was created.

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

The ID of the created reference, if created

async 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.\n\n**Allowed values**:\n\n- `public`: Visible to the general public without authentication.\n- `restricted`: Requires authentication to be visible.\n- `hidden`: Is not visible, but may be passed to data mining processes.",
         "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