Metadata Extension

The Metadata Extension (gpkg_metadata) provides a standard mechanism for embedding metadata documents inside a GeoPackage. Metadata is stored in the gpkg_metadata table and linked to GeoPackage objects (the file, specific tables, columns, or rows) through the gpkg_metadata_reference table.

This is an OGC-registered extension defined at http://www.geopackage.org/spec/#extension_metadata.

Core Tables

Table	Purpose
`gpkg_metadata`	Stores the raw metadata documents (XML, JSON, text, etc.)
`gpkg_metadata_reference`	Links metadata documents to GeoPackage objects

Key Classes

`MetadataExtension`

Manages the lifecycle of the extension itself (registration, table creation, removal).

import { MetadataExtension } from '@ngageoint/geopackage';

const metaExt = new MetadataExtension(geoPackage);

// Register the extension and create tables
metaExt.getOrCreateExtension();

// Check presence
const hasMetadata = metaExt.has();

// Remove all metadata tables and extension registrations
metaExt.removeExtension();

`Metadata`

A row in gpkg_metadata. Stores the document content and describes its encoding.

number

Auto-assigned primary key.

md_scope

string

Scope string from MetadataScopeType (e.g. 'dataset', 'table'). Describes what the metadata applies to.

md_standard_uri

string

URI identifying the metadata standard (e.g. http://www.isotc211.org/2005/gmd for ISO 19139).

mime_type

string

MIME type of the encoded metadata (e.g. text/xml, application/json).

metadata

string

The raw metadata document content.

`MetadataReference`

A row in gpkg_metadata_reference. Links a Metadata document to a specific target object.

reference_scope

string

One of the ReferenceScopeType values: geopackage, table, column, row, row/col.

table_name

string

Target table name. NULL when reference_scope is geopackage.

column_name

string

Target column name. Set only for column or row/col scopes.

row_id_value

number

Target row ID. Set only for row or row/col scopes.

md_file_id

number

Foreign key to gpkg_metadata.id.

md_parent_id

number | null

Optional foreign key to a parent gpkg_metadata.id for hierarchical metadata.

`MetadataScopeType` Values

The scope describes what entity the metadata document is about:

All MetadataScopeType values

Value	String	Description
`UNDEFINED`	`undefined`	Scope is undefined
`FIELD_SESSION`	`fieldSession`	Applies to a field data collection session
`COLLECTION_SESSION`	`collectionSession`	Applies to a collection session
`SERIES`	`series`	Applies to a dataset series
`DATASET`	`dataset`	Applies to a geographic feature dataset
`FEATURE_TYPE`	`featureType`	Applies to a feature type (class)
`FEATURE`	`feature`	Applies to a single feature instance
`ATTRIBUTE_TYPE`	`attributeType`	Applies to an attribute class
`ATTRIBUTE`	`attribute`	Applies to a feature attribute
`TILE`	`tile`	Applies to a tile
`MODEL`	`model`	Applies to a model
`CATALOG`	`catalog`	Applies to a feature catalog
`SCHEMA`	`schema`	Applies to an application schema
`TAXONOMY`	`taxonomy`	Applies to a taxonomy or knowledge system
`SOFTWARE`	`software`	Applies to software
`SERVICE`	`service`	Applies to a service
`COLLECTION_HARDWARE`	`collectionHardware`	Applies to collection hardware
`NON_GEOGRAPHIC_DATASET`	`nonGeographicDataset`	Applies to non-geographic data
`DIMENSION_GROUP`	`dimensionGroup`	Applies to a dimension group
`STYLE`	`style`	Applies to a specific style

`ReferenceScopeType` Values

Controls what GeoPackage object a MetadataReference row points to:

Value	String	Points to
`GEOPACKAGE`	`geopackage`	The entire GeoPackage file
`TABLE`	`table`	A specific table
`COLUMN`	`column`	A specific column in a table
`ROW`	`row`	A specific row in a table
`ROW_COL`	`row/col`	A specific cell (row + column)

Creating and Attaching Metadata

Initialize the extension

import {
  GeoPackageAPI,
  MetadataExtension,
  Metadata,
  MetadataReference,
  MetadataScopeType,
  ReferenceScopeType,
} from '@ngageoint/geopackage';

const geoPackage = await GeoPackageAPI.open('my.gpkg');
const metaExt = new MetadataExtension(geoPackage);
metaExt.getOrCreateExtension();

Create a Metadata document

const metadataDao = geoPackage.getMetadataDao();

const meta = new Metadata();
meta.md_scope    = MetadataScopeType.DATASET;
meta.md_standard_uri = 'http://www.isotc211.org/2005/gmd';
meta.mime_type   = 'text/xml';
meta.metadata    = `<gmd:MD_Metadata>...</gmd:MD_Metadata>`;

const metaId = metadataDao.create(meta);

Create a MetadataReference linking the document to a table

const refDao = geoPackage.getMetadataReferenceDao();

const ref = new MetadataReference();
ref.reference_scope = ReferenceScopeType.TABLE;
ref.table_name      = 'my_features';
ref.md_file_id      = metaId;
ref.md_parent_id    = null;
ref.timestamp       = new Date().toISOString();

refDao.create(ref);

Attaching Metadata to a Specific Row

const rowRef = new MetadataReference();
rowRef.reference_scope = ReferenceScopeType.ROW;
rowRef.table_name      = 'my_features';
rowRef.row_id_value    = 42;          // the feature's row ID
rowRef.md_file_id      = metaId;
rowRef.timestamp       = new Date().toISOString();

refDao.create(rowRef);

Querying Metadata for a Table

const refDao = geoPackage.getMetadataReferenceDao();
const metadataDao = geoPackage.getMetadataDao();

// Get all references pointing to 'my_features'
const refs = refDao.queryByTableName('my_features');

for (const ref of refs) {
  const doc = metadataDao.queryForId(ref.md_file_id);
  console.log('Scope:', doc.md_scope);
  console.log('Standard:', doc.md_standard_uri);
  console.log('Content:', doc.metadata);
}

GeoPackage-Level Metadata

// Attach metadata to the GeoPackage file itself
const gpkgRef = new MetadataReference();
gpkgRef.reference_scope = ReferenceScopeType.GEOPACKAGE;
gpkgRef.table_name      = null;
gpkgRef.md_file_id      = metaId;
gpkgRef.timestamp       = new Date().toISOString();

refDao.create(gpkgRef);

Use MetadataScopeType.DATASET for dataset-level ISO 19115 records and MetadataScopeType.FEATURE for per-row provenance or quality metadata. Keep MIME types accurate (text/xml, application/json, text/plain) so consumers can decode the content correctly.

Get Started

Core Concepts

Guides

Extensions

Core Tables

Key Classes

`MetadataExtension`

`Metadata`

`MetadataReference`

`MetadataScopeType` Values

`ReferenceScopeType` Values

Creating and Attaching Metadata

Attaching Metadata to a Specific Row

Querying Metadata for a Table

GeoPackage-Level Metadata

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Extensions

​Core Tables

​Key Classes

​MetadataExtension

​Metadata

​MetadataReference

​MetadataScopeType Values

​ReferenceScopeType Values

​Creating and Attaching Metadata

​Attaching Metadata to a Specific Row

​Querying Metadata for a Table

​GeoPackage-Level Metadata

Build docs developers (and LLMs) love

Core Tables

Key Classes

`MetadataExtension`

`Metadata`

`MetadataReference`

`MetadataScopeType` Values

`ReferenceScopeType` Values

Creating and Attaching Metadata

Attaching Metadata to a Specific Row

Querying Metadata for a Table

GeoPackage-Level Metadata