MAGIC Administration (v1)

About

Details

Title: 'British Antarctic Survey (BAS) Mapping and Geographic Information Centre (MAGIC) Administration Metadata Profile'

Edition: 1

Revision: 2025-10-22

Licence: Open Government Licence

People

Authors:

Contributors:

Reviewers:

Contents

Note

Terms including 'MUST', 'SHOULD', 'MAY' etc. are used according to RFC 2119.

Rational

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 administration information is not accessible to external users
  • ensuring the integrity and trustworthiness of administration 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, targeted, information needed for internal administration, held within ISO 19115 records.

Base standard

Not Applicable.

In most cases, records will also follow the MAGIC Discovery profile.

Definition

This profile consists of two parts:

  1. the structure of administration metadata (Content Model)
  2. the method for storing administration metadata (Encoding)

JSON Schemas

Examples

  • content model (minimal)
  • content model (complete)
  • minimal record encoding:
    • JSON (BAS ISO 19115 schema)
    • XML (ISO 19139)

Note

Encoded administration metadata has been intentionally encrypted and signed using shared insecure Test Keys, to allow anyone to decode their contents.

Content model specification

Overview

Note

This section is informative only.

The content model is authoritatively defined by the content model JSON Schema.

Note

These properties are not part of the ISO 19115 information model.

Property Name Type Format Obligation Occurrence
$schema Schema String URI Mandatory 1
id ID String URI Mandatory 1
gitlab_issues GitLab Issues Array - Optional 0..*
metadata_permissions Metadata Permissions Array Access Permissions Mandatory 0..*
resource_permissions Resource Permissions Array Access Permissions Mandatory 0..*

Where GitLab issues are defined as:

Property Name Type Format Obligation Occurrence
* GitLab issue String URI Mandatory 1

Where Access permissions are defined as:

Property Name Type Format Obligation Occurrence
* Access permission Object - Mandatory 1
*.directory Directory identifier String - Mandatory 1
*.group Group identifier String - Mandatory 1
*.expiry Expires at String Datetime Mandatory 1
*.comment Comment String - Optional 0..1

Properties

Schema

As defined by the JSON Schema $schema property.

Distinguishes different versions of the MAGIC Administration 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

ID

Distinguishes administration metadata instances.

This property MUST relate administration metadata to wider discovery metadata for the described resource.

This property value MUST therefore be equal to the described resource's file_identifier discovery metadata value.

GitLab issues

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.

Warning

This property MUST NOT be used for issues from any other systems (such as GitHub) to ensure URLs are in a known format.

Metadata permissions

Access Permissions relating to the description of the resource being described.

I.e. Who can view information about the data/service/etc.

SHOULD be used by data discovery systems as a source of truth to configure access permissions.

Resource permissions

Access Permissions relating to the resource being described.

I.e. Who can download or access the data/service/etc.

SHOULD be used by data access systems as a source of truth to configure access permissions.

Access permissions

Groups within an identity provider (directory) that can access some information until a specified time, with an optional free-text comment explaining why access has been granted.

Warning

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 access systems MUST support.

Encoding specification

Overview

Administration metadata MUST be:

  1. encoded as a JSON string
  2. added to a JSON Web Token (JWT) using a pyd Private Claim
  3. encrypted using JSON Web Encryption (JWE)

I.e.:

[JWE]
  └── [JWT]
        └── ['pyd'] (private claim)
              └── [Administration Metadata content model instance as JSON string]

The outer JWE ensures administration metadata is not accessible to external users (via encryption), whilst the inner JWT allows the integrity and trustworthiness of administration information to be verified (via signing).

The JWE MUST be contained in Discovery Metadata for the described resource.

JWT claims

Administration Metadata JWTs MUST contain these claims:

Claim Name Definition Value
pyd Payload - JSON encoded administration 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 (for the lifetime of the resource).

Administration 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

JWT signing key

JWTs MUST be signed using the private MAGIC Administration Metadata Signing Key.

JWTs MUST be verified using the related public key.

JWE encryption key

JWEs MUST be encrypted using the public key derived from the MAGIC Administration Metadata Encryption Key.

JWEs MUST be decrypted using the related private Key.

Discovery metadata

Note

This subsection is informative only. It is authoritatively defined by the encoding JSON Schema.

The JWE value MUST be:

  • contained in a JSON encoded key-value object under an 'admin_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]
│             └── {"admin_metadata": "[JWE]"}
└── [Data Quality]
    └── [Domain Consistency]

Tip

The supplemental information key-value object MAY contain additional keys.

Reference implementations

The get_admin and set_admin methods, and their associated documentation, form a reference Python implementation for encoding and decoding administration metadata using Python.

Example objects

ISO 19115 supplemental information value:

"supplemental_information": "{\"admin_metadata\": \"eyJjdHkiOiJKV1QiLCJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiJuYkxSS2tnYXRSalFwZlR1aTVCYWFyUGx0UXV0OG5yT3ROOHJ1M19DQTRrIiwieSI6ImM0aGQ0TzJ6bVdtY3pDeVZ1aTU0LS1GTU9HUGRqbEoyNlV0Z1hNVUdfVUUifSwiYWxnIjoiRUNESC1FUytBMTI4S1ciLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiYmFzX21ldGFkYXRhX3Rlc3RpbmdfZW5jcnlwdGlvbl9rZXkifQ.BeIXhmz3HLB_SGOf21J2o-gErnXgRRTkjXAH_U9y3ZAp6BixciVzSg.o68vlPjI7s_x4bL_.d-wXqU4dPIX9_FJg9LT-cpneJsNFfA8FXg9vIA9Jqeo75Sbmhp4Ugedl6Vhibm-uf7RJUmX46dusNk20n42oFje-eiJ53SZ53ak6d85GQSKhZCzfd6lA43HLEnyjrt7z_5dBZisk6RaIc4aEMUm2CY5P4QBr2WMIXtjUctWL2591wbC-JaQWTfrnouIg2YKxUNQyp3FxdSgNzZ30ThWBcktEGu9bKKqNWI_pokx8RqWjXx719STT9xRcKrv-kUYsrELPYScHWgXd6CmA0rsSQVpO0u7zKEndVXZIAOWM7kNGQ1kLSsLOziF6rZRyDM5B4m3VkItiekq4evHi91h-EHlfX8g8cMQ5OgHaUnVsPmwlDTRcbNapGmp_cbLLVnVncrTHlbtvafz9C2XTsQyRORwXk9hBSduQq3ezBL1WiubMo5DaFjFCCYv-QSrnXJvDb_zbgERHytQ-ieOlZB6NTh6ptSnJ17E8DsccUKii2PWCc5U8t5hFZuqYhvDRZ68n6md0S-ouESf5D32WgQYq_BrFpGIrUgRXcFLgI0wXtkErYr43IOV3KLaNy0cqf-YPmymDKbqHia3QYp4HjWab_5-XsOU_pYy4pK_HvUlyUkz6gL3BfTPMr852-VRLO6VqVzaO_41xAEgxX4n1AvHjGIsFb3YwP-txUs-BANj73-CiYHko1YB5fkLHOKqt2_i4-3UsKhl4TATRQLhaJE6Ijujry8qNB4z0SwD1rOPaF_sGZ7Y5eMEvw8SarcMjAlJYzxTXBeCYOBx1JmLK43wvl6DTKuPs0Ai9Rm-Wbwx8IunoQ65hNltZ_c0Cy4RYzv_lW_7jfG3jbsJzdZKBl5T6LtNmLvLxMccemmj4maTANyUeta3GB7kHYgglhUVFxe9c4TWvD_9w8wYhKJdseTxs6VwC7Gxo20O93-rH0Zeqyw-WpyF85ChYZJATyM1c2sZEXxNEC0YsaJGooYYZ6fDyU6nyINjjPjn5olDGyZsXK8nZSQ5tHbdkuD_zjm1O2-wxLlTFmpg_WWgREnVhIAAjUXTYiJjFfFcsRRzeB1KAgh5f2wA1BsD4GQP50QgAgpxK3Ixx8ItK.xXALXB9ZYPbkVyz4f41okA\"}"

JSON Web Encryption value:

eyJjdHkiOiJKV1QiLCJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiJuYkxSS2tnYXRSalFwZlR1aTVCYWFyUGx0UXV0OG5yT3ROOHJ1M19DQTRrIiwieSI6ImM0aGQ0TzJ6bVdtY3pDeVZ1aTU0LS1GTU9HUGRqbEoyNlV0Z1hNVUdfVUUifSwiYWxnIjoiRUNESC1FUytBMTI4S1ciLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiYmFzX21ldGFkYXRhX3Rlc3RpbmdfZW5jcnlwdGlvbl9rZXkifQ.BeIXhmz3HLB_SGOf21J2o-gErnXgRRTkjXAH_U9y3ZAp6BixciVzSg.o68vlPjI7s_x4bL_.d-wXqU4dPIX9_FJg9LT-cpneJsNFfA8FXg9vIA9Jqeo75Sbmhp4Ugedl6Vhibm-uf7RJUmX46dusNk20n42oFje-eiJ53SZ53ak6d85GQSKhZCzfd6lA43HLEnyjrt7z_5dBZisk6RaIc4aEMUm2CY5P4QBr2WMIXtjUctWL2591wbC-JaQWTfrnouIg2YKxUNQyp3FxdSgNzZ30ThWBcktEGu9bKKqNWI_pokx8RqWjXx719STT9xRcKrv-kUYsrELPYScHWgXd6CmA0rsSQVpO0u7zKEndVXZIAOWM7kNGQ1kLSsLOziF6rZRyDM5B4m3VkItiekq4evHi91h-EHlfX8g8cMQ5OgHaUnVsPmwlDTRcbNapGmp_cbLLVnVncrTHlbtvafz9C2XTsQyRORwXk9hBSduQq3ezBL1WiubMo5DaFjFCCYv-QSrnXJvDb_zbgERHytQ-ieOlZB6NTh6ptSnJ17E8DsccUKii2PWCc5U8t5hFZuqYhvDRZ68n6md0S-ouESf5D32WgQYq_BrFpGIrUgRXcFLgI0wXtkErYr43IOV3KLaNy0cqf-YPmymDKbqHia3QYp4HjWab_5-XsOU_pYy4pK_HvUlyUkz6gL3BfTPMr852-VRLO6VqVzaO_41xAEgxX4n1AvHjGIsFb3YwP-txUs-BANj73-CiYHko1YB5fkLHOKqt2_i4-3UsKhl4TATRQLhaJE6Ijujry8qNB4z0SwD1rOPaF_sGZ7Y5eMEvw8SarcMjAlJYzxTXBeCYOBx1JmLK43wvl6DTKuPs0Ai9Rm-Wbwx8IunoQ65hNltZ_c0Cy4RYzv_lW_7jfG3jbsJzdZKBl5T6LtNmLvLxMccemmj4maTANyUeta3GB7kHYgglhUVFxe9c4TWvD_9w8wYhKJdseTxs6VwC7Gxo20O93-rH0Zeqyw-WpyF85ChYZJATyM1c2sZEXxNEC0YsaJGooYYZ6fDyU6nyINjjPjn5olDGyZsXK8nZSQ5tHbdkuD_zjm1O2-wxLlTFmpg_WWgREnVhIAAjUXTYiJjFfFcsRRzeB1KAgh5f2wA1BsD4GQP50QgAgpxK3Ixx8ItK.xXALXB9ZYPbkVyz4f41okA

Decrypted JSON Web Token value:

{
  'pyd': '{\n  "$schema": "https://metadata-resources.data.bas.ac.uk/bas-metadata-generator-configuration-schemas/v2/magic-administration-content-v1.json",\n  "id": "c321cfb7-5541-4881-88cc-73f2a4a8f533",\n  "gitlab_issues": [],\n  "metadata_permissions": [],\n  "resource_permissions": []\n}', 
  'iss': 'magic.data.bas.ac.uk', 
  'aud': 'data.bas.ac.uk', 
  'sub': 'c321cfb7-5541-4881-88cc-73f2a4a8f533', 
  'iat': 1771277833, 
  'exp': 4924877833, 
  'jti': '1325e848-ee50-418f-83e4-187e3e15d369'
}

Decoded pyd JWT claim value:

{
  "$schema": "https://metadata-resources.data.bas.ac.uk/bas-metadata-generator-configuration-schemas/v2/magic-administration-content-v1.json",
  "id": "c321cfb7-5541-4881-88cc-73f2a4a8f533",
  "gitlab_issues": [],
  "metadata_permissions": [],
  "resource_permissions": []
}

Appendices

Appendix 1 - Domain Consistency Element

{
    "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 the British Antarctic Survey (BAS) Mapping and Geographic Information Centre (MAGIC) Administration Metadata Profile.",
    "result": true
}

Appendix 2 - Minimum supported access permissions

Open access

Access Permission granting anonymous access to information (i.e. unrestricted access).

Used for information intended for public release or that does not otherwise need to be restricted.

Property Value Explanation
directory * Representing any directory
group * Representing any user in any directory

BAS Staff access

Access Permission granting any British Antarctic Survey (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 restricted to within BAS (only).

Property Value Explanation
directory ~nerc Representing the BAS IdP provider directory
group ~bas-staff Representing all BAS staff

Appendix 3 - MAGIC Administration Metadata Signing Key

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.

Appendix 4 - MAGIC Administration Metadata Encryption Key

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.