Important
Pre-publication links for reviewers:
- content model (minimal)(JSON)
- content model (complete)(JSON)
- content encoding (JSON)
- content encoding (XML) - Unavailable
- Test Keys
Details
Title: 'British Antarctic Survey (BAS) Mapping and Geographic Information Centre (MAGIC) Administrative Metadata Profile'
Edition: 1
Revision: 2025-10-22
Licence: Open Government Licence
Note
Terms including 'MUST', 'SHOULD', 'MAY' etc. are used according to RFC 2119.
The ISO 19115 information model and the open, non-verifiable, nature of discovery metadata are not sufficient to meet MAGIC's needs for managing resources administratively, including:
- ensuring administrative information is not accessible to external users
- ensuring the integrity and trustworthiness of administrative information can be verified
- ensuring access constraints are captured in sufficient detail, as MAGIC routinely handles sensitive, licensed or otherwise restricted information
- ensuring references to internal systems are not visible to end-users, as such information MUST NOT be accessible to unintended audiences
In essence, this profile aims to compliment discovery metadata with additional, targetted, information needed for internal administration, held within ISO 19115 records.
This profile is based on the ISO 19115-2:2009 standard, specifically the gmd:supplementalInformation element.
Important
This is a preemptive link.
In most cases, records will also follow the MAGIC Discovery profile to set discovery metadata.
This profile consists of two parts:
- the structure of administrative metadata (Content Model)
- the method for storing administrative metadata (Encoding)
Important
These are preemptive links.
Important
These are preemptive links.
- content model (minimal) JSON
- content model (complete) JSON
- minimal record encoding JSON | XML
- a minimal ISO 19115 record including administrative metadata
Note
Encoded administrative metadata has been intentionally encrypted and signed using shared insecure Test Keys, to allow anyone to decode their contents.
Note
This section is informative only.
The content model is authoriatively defined by the content model JSON Schema.
| Property | Name | Type | Format |
|---|---|---|---|
$schema |
Schema | String | URI |
id |
ID | String | URI |
gitlab_issues |
GitLab issues | Array | - |
gitlab_issues.* |
GitLab issue | String | URI |
access_permissions |
Access permissions | Array | - |
access_permissions.* |
Access permission | Object | - |
access_permissions.*.directory |
Directory identifier | String | - |
access_permissions.*.group |
Group identifier | String | - |
access_permissions.*.expiry |
Expiries at | String | Datetime |
access_permissions.*.comments |
Comments | String | - |
Note
These properties do not form part of the ISO 19115 information model.
Types and formats are used according to the JSON Schema specification.
As defined by the JSON Schema $schema property.
Distinguishes different versions of the MAGIC Administrative Metadata content model.
This property value MUST be set to https://metadata-resources.data.bas.ac.uk/bas-metadata-generator-configuration-schemas/v2/magic-admin-v1.json.
Distinguishes administrative metadata instances.
This property MUST relate administrative metadata to wider discovery metadata for the described resource.
This property value MUST therefore be set to the file_identifier discovery metadata value for the described resource.
Non-public information, history and/or context captured in GitLab issues about the resource.
This property CAN be used with issues from any GitLab instance.
This property MUST NOT be used for issues from any other systems (such as GitHub), as the form of issue URLs MAY be relied up (to construct shorthand references for example).
Groups within a directory that have access to the resource, optionally limited in duration and/or explained via a freetext comment.
SHOULD be used by data access systems as a source of truth to configure access permissions. The comments sub-property MUST NOT be used by any system to configure permissions.
The directory and group sub-properties MAY use identifiers from an identity provider, or aliases for such identifiers where these are mutually understood by different systems.
See Appendix 2 for aliases systems MUST support.
Administrative metadata MUST be:
- encoded as a JSON string
- added to a JSON Web Token (JWT) using a
pyd[Private Claim] (https://datatracker.ietf.org/doc/html/rfc7519#section-4.3) - encrypted using JSON Web Encryption (JWE)
I.e.:
[JWE]
└── [JWT]
└── ['pyd'] (private claim)
└── [Administrative Metadata content model instance as JSON string]
The outer JWE ensures administrative metadata is not accessible to external users (via encryption), whilst the inner JWT allows the integrity and trustworthiness of administrative information to be verified (via signing).
The JWE MUST be contained in Discovery Metadata for the described resource.
Administrative Metadata JWTs MUST contain these claims:
| Claim | Name | Definition | Value |
|---|---|---|---|
pyd |
Payload | - | JSON encoded administrative metadata |
iss |
Issuer | RFC 7519 | magic.data.bas.ac.uk |
aud |
Audience | RFC 7519 | data.bas.ac.uk |
exp |
Expiry | RFC 7519 | 100 years from point of issue |
Note
JWTs typically use a short expiry time for prevent long-lived credentials. These tokens are not used for credentials or an identity, and are intentionally long lived (from the point of issue for the lifetime of the record).
Administrative Metadata JWTs MAY contain these claims:
| Claim | Name | Definition | Value |
|---|---|---|---|
sub |
Subject | RFC 7519 | Related record file identifier and admin metadata ID |
nbf |
Not before | RFC 7519 | Point of issue |
iat |
Issued at | RFC 7519 | Point of issue |
JWTs MUST be signed using the private MAGIC Administrative Metadata Signing Key.
JWTs MUST be verified using the related public key.
JWEs MUST be encrypted using the public key derived from the MAGIC Administrative Metadata Encryption Key.
JWEs MUST be decrypted using the related private Key.
Note
This sub-section is informative only. It is authoriatively defined by the encoding JSON Schema.
The JWE value MUST be:
- contained in a JSON encoded key-value object under an 'administrative_metadata' key
- set as the Supplemental Information element
- in discovery metadata for the described resource
THis discovery metadata MUST also include:
- the file identifier element, using a value that is unique across all records
- a domain consistency data quality element as per Appendix 1 - Domain Consistency Element, stating the record complies with this profile (for validation tools to determine whether a record uses this profile)
I.e.:
[Discovery Metadata]
├── [File Identifier]
├── [Identification]
│ └── [Supplemental Information]
│ └── [JWE]
│ └── ...
└── [Data Quality]
└── [Domain Consistency]
Tip
The supplemental information key-value object MAY contain additional keys as desired.
The get_admin and set_admin methods, and their associated documentation, form a reference implementation using Python.
{
"specification": {
"dates": {
"publication": "2025-10-22"
},
"edition": "1",
"title": {
"value": "British Antarctic Survey (BAS) Mapping and Geographic Information Centre (MAGIC) Administration Metadata Profile",
"href": "https://metadata-standards.data.bas.ac.uk/profiles/magic-administration/v1/"
},
"contact": {
"organisation": {
"name": "Mapping and Geographic Information Centre, British Antarctic Survey",
"href": "https://ror.org/01rhff309",
"title": "ror"
},
"phone": "+44 (0)1223 221400",
"address": {
"delivery_point": "British Antarctic Survey, High Cross, Madingley Road",
"city": "Cambridge",
"administrative_area": "Cambridgeshire",
"postal_code": "CB3 0ET",
"country": "United Kingdom"
},
"email": "magic@bas.ac.uk",
"online_resource": {
"href": "https://www.bas.ac.uk/teams/magic",
"title": "Mapping and Geographic Information Centre (MAGIC) - BAS public website",
"description": "General information about the BAS Mapping and Geographic Information Centre (MAGIC) from the British Antarctic Survey (BAS) public website.",
"function": "information"
},
"role": [
"publisher"
]
}
},
"explanation": "Resource within scope of British Antarctic Survey (BAS) Mapping and Geographic Information Centre (MAGIC) Administrative Metadata Profile.",
"result": true
}Grants anyone access to information (i.e. unrestricted and anonymous access).
Used for information that is intended for public release or that does not otherwise need to be restricted.
| Property | Value | Meaning |
|---|---|---|
access_permissions.*.directory |
* |
Representing any directory |
access_permissions.*.group |
~public |
Representing the opposite of private |
Grants any BAS staff member access to information, excluding wider UKRI staff.
Warning
This access permission is underpinned by a dynamic group controlled by UKRI. This group's composition criteria are not known, and it is not guaranteed to exclusively contain BAS staff.
Used for information that is restricted internally within BAS (only).
| Property | Value | Meaning |
|---|---|---|
access_permissions.*.directory |
* |
Representing any directory |
access_permissions.*.group |
~bas-staff |
Representing all BAS staff |
Public JSON Web Key (JWK):
{
"kty":"EC",
"kid":"magic_metadata_signing_key",
"alg":"ES256",
"crv":"P-256",
"x":"Ksei1ZoTIBRQrJZeNRzdch9910T7hqKjRSqq0wkNxRQ",
"y":"SykdLryiLm3xNHEiC_OYmB6jzaU1ZtyRv8WfxMIRdJ4"
}Note
Private key material for this key is available by contacting MAGIC.
Public JSON Web Key (JWK):
{
"kty":"EC",
"kid":"magic_metadata_encryption_key",
"alg":"ECDH-ES+A128KW",
"crv":"P-256",
"x":"n_SWT2v7lyte0Kgdozc8CO_cJNEjW-s7cRR3plMK_wo",
"y":"e2TioKjehKX_IgGHZ-Zl0q70jv6cANHWToHWQ507e5U"
}Note
Private key material for this key is available by contacting MAGIC.