Object Lifecycle¶
Retrieval (GET)¶
Data can be retrieved from the database in one of a few “frames” which specify how much data is in the returned object. The object and embedded frames are indexed in elasticsearch, the page properties are applied at “GET”. Usually you will specify format=json (or set content-type: application/json) if you wish to return a JSON object directly.
- frame=raw
Objects are stored in the DB “raw” - with only the properties that are submitted with links as uuids.
- frame=object
This is the raw object with additional “@properties” (@id, @type) and calculated properties (defined in python code “types” package).
- frame=edit
This is the frame=object without calculated properties
- frame=embedded
This is the frame=object object with all the embedded properties (also specified in the “types” package)
- frame=page
This is the default object returned if frame is not specified. It is the frame=embedded object with several UI and form properties added including @context, aggregated items, validation errors, and user actions.
Submission (POST)¶
POST /biosample:
{
"biosample_type": "DNA",
"biosample_term_id": "UBERON:349829",
"aliases": ["my-lab:sample1"],
"award": "my-award",
"lab": "my-lab",
"source": "some-source",
"organism": "human"
}
Validation¶
- Does submission conform to schema?
- Structural conformance
- Link resolution
- Value format validation
- Permission checking
- Are calculated properties legal?
Link resolution¶
Links are resolved relative to their configured base url, normally their collection. Absolute paths and UUIDs are also valid, as are aliases and other uniquely identifying properties:
{
"award": "fae1bd8b-0d90-4ada-b51f-0ecc413e904d",
"lab": "b635b4ed-dba3-4672-ace9-11d76a8d03af",
"source": "1d5be796-8f80-4fd4-b6c7-6674318657eb",
"organism": "7745b647-ff15-4ff3-9ced-b897d4e2983c"
}
Default values¶
Static and calculated defaults:
{
"uuid": "7c245cea-7d59-45fb-9ebe-f0454c5fe950"
"accession": "ENCBS000TST",
"date_created": "2014-01-20T10:30:00-0800",
"status": "IN PROGRESS",
"submitted_by": "bb319896-3f78-4e24-b6e1-e4961822bc9b"
}
Storage¶
Resource record created for uuid with item_type:
uuid: "7c245cea-7d59-45fb-9ebe-f0454c5fe950"
item_type: "biosample"
Raw properties:
{
"biosample_type": "DNA",
"biosample_term_id": "UBERON:349829",
"aliases": ["my-lab:sample1"],
"award": "fae1bd8b-0d90-4ada-b51f-0ecc413e904d",
"lab": "b635b4ed-dba3-4672-ace9-11d76a8d03af",
"source": "1d5be796-8f80-4fd4-b6c7-6674318657eb",
"organism": "7745b647-ff15-4ff3-9ced-b897d4e2983c",
"accession": "ENCBS000TST",
"date_created": "2014-01-20T10:30:00-0800",
"status": "IN PROGRESS",
"submitted_by": "bb319896-3f78-4e24-b6e1-e4961822bc9b"
}
Rows are inserted to enforce unique constraints:
keys: [
("accession", "ENCBS000TST"),
("alias", "my-lab:sample1"),
]
and to maintain referential integrity:
links: [
("award", "fae1bd8b-0d90-4ada-b51f-0ecc413e904d"),
("lab", "b635b4ed-dba3-4672-ace9-11d76a8d03af"),
("source", "1d5be796-8f80-4fd4-b6c7-6674318657eb"),
("organism", "7745b647-ff15-4ff3-9ced-b897d4e2983c"),
("submitted_by", "bb319896-3f78-4e24-b6e1-e4961822bc9b"),
]
- Also:
- additional property sheets
- transaction logging
- object versioning
Rendering¶
* raw properties
-> link canonicalization
-> calculated properties
-> embedding
-> page expansion
Link Canonicalization¶
Specified in the schema. UUID’s are converted to resource paths.
{
"award": "/awards/my-award/",
"lab": "/labs/my-lab",
"source": "/sources/some-source/",
"organism": "/organisms/human/",
"submitted_by": "/users/me/",
}
Calculated Properties¶
These include the JSON-LD boilerplate along with other dynamically calculated properties such as a consistently formatted title and reverse links pulled from the links table.
{
"@id": "/biosamples/ENCBS000TST/",
"@type": ["biosample", "item"],
"uuid": "7c245cea-7d59-45fb-9ebe-f0454c5fe950"
"name": "ENCBS000TST",
"title": "Biosample ENCBS000TST (human)",
"characterizations": [],
}
Calculated properties can be top level fields or sub-embedded object fields. See the end of testing_views.py to see how one would declare a calculated property on a sub-embedded object.
JSON result¶
Combining gives us:
{
"biosample_type": "DNA",
"biosample_term_id": "UBERON:349829",
"aliases": ["my-lab:sample1"],
"accession": "ENCBS000TST",
"date_created": "2014-01-20T10:30:00-0800",
"status": "IN PROGRESS",
"award": "/awards/my-award/",
"lab": "/labs/my-lab",
"source": "/sources/some-source/",
"organism": "/organisms/human/",
"submitted_by": "/users/me/",
"@id": "/biosamples/ENCBS000TST/",
"@type": ["biosample", "item"],
"uuid": "7c245cea-7d59-45fb-9ebe-f0454c5fe950"
"name": "ENCBS000TST",
"title": "Biosample ENCBS000TST (human)",
"characterizations": [],
}
This is the representation returned within the POST/PUT/PATCH result and when specifying frame=object
within the query parameters.
Embedding¶
Each object type specifies its embedded properties, for biosample we have:
[
"donor.organism",
"submitted_by",
"lab",
"award",
"source",
"treatments.protocols.submitted_by",
"treatments.protocols.lab",
"treatments.protocols.award",
"constructs.documents.submitted_by",
"constructs.documents.award",
"constructs.documents.lab",
"constructs.target",
"protocol_documents.lab",
"protocol_documents.award",
"protocol_documents.submitted_by",
"derived_from",
"part_of",
"pooled_from",
"characterizations.submitted_by",
"characterizations.award",
"characterizations.lab",
"rnais.target.organism",
"rnais.source",
"rnais.documents.submitted_by",
"rnais.documents.award",
"rnais.documents.lab",
"organism"
]
The specified links are then replaced with objects:
{
"biosample_type": "DNA",
"biosample_term_id": "UBERON:349829",
"aliases": ["my-lab:sample1"],
"accession": "ENCBS000TST",
"date_created": "2014-01-20T10:30:00-0800",
"status": "IN PROGRESS",
"award": {
"@id": "/awards/my-award/",
"@type": ["award", "item"],
"uuid": "fae1bd8b-0d90-4ada-b51f-0ecc413e904d",
"name": "my-award"
},
"lab": {
"@id": "/labs/my-lab",
"@type": ["lab", "item"],
"uuid": "b635b4ed-dba3-4672-ace9-11d76a8d03af",
"name": "my-lab",
"title": "My Lab"
},
"source": {
"@id": "/sources/some-source/",
"@type": ["source", "item"],
"uuid": "1d5be796-8f80-4fd4-b6c7-6674318657eb",
"name": "some-source",
"title": "Some source"
},
"organism": {
"@id": "/organisms/human/",
"@type": ["organism", "item"],
"uuid": "7745b647-ff15-4ff3-9ced-b897d4e2983c",
"name": "human",
"scientific_name": "Homo sapiens",
"taxon_id": "9606",
},
"submitted_by": {
"@id": "/users/me/",
"@type": ["user", "item"],
"uuid": "bb319896-3f78-4e24-b6e1-e4961822bc9b",
"title": "My Name",
"lab": "/labs/my-lab"
},
"@id": "/biosamples/ENCBS000TST/",
"@type": ["biosample", "item"],
"uuid": "7c245cea-7d59-45fb-9ebe-f0454c5fe950"
"name": "ENCBS000TST",
"title": "Biosample ENCBS000TST (human)",
"characterizations": [],
}
This embedded object is indexed in elasticsearch to allow searching and faceting across the embedded values.
It is returned when when specifying frame=embedded
within the query parameters.
Page expansion¶
The final step in the rendering pipeline is applied only to single items, not to search results. It provides the opportunity to add properties that are restricted or tailored to certain users, such as the user actions:
{
"actions": [
{
"profile": "/profiles/biosample.json",
"href": "/biosamples/ENCBS000TST/#!edit",
"name": "edit",
"title": "Edit"
},
{
"profile": "/profiles/biosample.json",
"href": "/biosamples/ENCBS000TST/#!edit-json",
"name": "edit-json",
"title": "Edit JSON"
}
]
}