types

type AllowedValue struct {
	// Value is the allowed value.
	Value string `json:"value"`

	// Description explains when to use this value.
	Description string `json:"description,omitempty"`
}

type AssertionResult struct {
	// AssertionURN identifies the assertion.
	AssertionURN string `json:"assertion_urn"`

	// Type is the assertion category: FRESHNESS, SCHEMA, or DATA_QUALITY.
	Type string `json:"type"`
}

type ColumnLineage struct {
	// DatasetURN is the URN of the dataset this lineage is for.
	DatasetURN string `json:"dataset_urn"`

	// Mappings contains the column-level lineage mappings.
	Mappings []ColumnLineageMapping `json:"mappings"`
}

type ColumnLineageMapping struct {
	// DownstreamColumn is the field path in the downstream dataset.
	DownstreamColumn string `json:"downstream_column"`

	// UpstreamDataset is the URN of the upstream dataset.
	UpstreamDataset string `json:"upstream_dataset"`

	// UpstreamColumn is the field path in the upstream dataset.
	UpstreamColumn string `json:"upstream_column"`

	// Transform describes the transformation operation (optional).
	// Examples: "IDENTITY", "TRANSFORM", "AGGREGATE"
	Transform string `json:"transform,omitempty"`

	// Query is the URN of the query that created this lineage (optional).
	Query string `json:"query,omitempty"`

	// ConfidenceScore indicates the confidence of the lineage mapping (optional).
	// Values typically range from 0.0 to 1.0.
	// Note: This field is not available in DataHub v1.3.x and will be zero.
	ConfidenceScore float64 `json:"confidence_score,omitempty"`
}

type ContextDocument struct {
	// ID is the document identifier (the portion after urn:li:document:).
	ID string `json:"id"`

	// Title is the document title.
	Title string `json:"title"`

	// Content is the document body text.
	Content string `json:"content,omitempty"`

	// ContentType describes the content format (e.g., "text/markdown").
	ContentType string `json:"content_type"`

	// Category classifies the document (maps to DataHub subType).
	Category string `json:"category,omitempty"`

	// CreatedAt is the creation timestamp (epoch ms).
	CreatedAt int64 `json:"created_at,omitempty"`

	// UpdatedAt is the last modification timestamp (epoch ms).
	UpdatedAt int64 `json:"updated_at,omitempty"`

	// Author is the primary author derived from ownership.
	Author *ContextDocumentAuthor `json:"author,omitempty"`
}

type ContextDocumentAuthor struct {
	// URN is the author entity URN (e.g., urn:li:corpuser:alice).
	URN string `json:"urn"`

	// Username is the author's login name extracted from a corpuser URN.
	// Empty for non-corpuser owners (e.g., corpGroup).
	Username string `json:"username,omitempty"`
}

type ContextDocumentInput struct {
	// ID is the document identifier. Empty means create; populated means update.
	ID string `json:"id,omitempty"`

	// Title is the document title (required).
	Title string `json:"title"`

	// Content is the document body text.
	Content string `json:"content"`

	// Category classifies the document (maps to DataHub subType).
	Category string `json:"category,omitempty"`
}

type CreateDocumentInput struct {
	// Title is the document title (required).
	Title string

	// Content is the document body text.
	Content string

	// Status is the publication state: PUBLISHED or UNPUBLISHED.
	Status string

	// SubType is the document sub-type classification.
	SubType string

	// RelatedAssetURNs are entity URNs to link to this document.
	RelatedAssetURNs []string

	// GlobalContext controls whether the document appears in global search.
	GlobalContext bool
}

type CreateStructuredPropertyInput struct {
	// QualifiedName is the fully qualified property name (required, e.g., "io.acryl.privacy.retentionTime").
	QualifiedName string

	// DisplayName is the human-readable name shown in the UI.
	DisplayName string

	// Description explains the purpose and usage of this property.
	Description string

	// ValueType is the data type for values (required, e.g., "string", "number", "date", "urn").
	ValueType string

	// Cardinality indicates whether the property accepts a single value or multiple.
	// Values: "SINGLE", "MULTIPLE". Defaults to "SINGLE".
	Cardinality string

	// EntityTypes lists which entity types this property can be applied to.
	EntityTypes []string

	// AllowedValues constrains the set of valid values when defined.
	AllowedValues []AllowedValue
}

type Dashboard struct {
	Entity

	// DashboardURL is the URL to the dashboard.
	DashboardURL string `json:"dashboard_url,omitempty"`

	// Charts lists the charts in this dashboard.
	Charts []string `json:"charts,omitempty"`
}

type DataContract struct {
	// Status is the overall contract state: PASSING, FAILING, or NOT_APPLICABLE.
	Status string `json:"status"`

	// AssertionResults contains the assertion references grouped by category.
	AssertionResults []AssertionResult `json:"assertion_results,omitempty"`
}

type DataProduct struct {
	URN         string            `json:"urn"`
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	Domain      *Domain           `json:"domain,omitempty"`
	Owners      []Owner           `json:"owners,omitempty"`
	Assets      []string          `json:"assets,omitempty"` // URNs of datasets
	Properties  map[string]string `json:"properties,omitempty"`
}

type Dataset struct {
	Entity

	// Schema contains the dataset schema.
	Schema *SchemaMetadata `json:"schema,omitempty"`

	// SubTypes are the dataset sub-types (table, view, etc.).
	SubTypes []string `json:"sub_types,omitempty"`
}

type Deprecation struct {
	// Deprecated: This field indicates if the entity is deprecated.
	Deprecated bool `json:"deprecated"`

	// Note is the deprecation note.
	Note string `json:"note,omitempty"`

	// Actor is who deprecated the entity.
	Actor string `json:"actor,omitempty"`

	// DecommissionTime is when the entity will be decommissioned.
	DecommissionTime int64 `json:"decommission_time,omitempty"`
}

type Document struct {
	// URN is the unique identifier (urn:li:document:{id}).
	URN string `json:"urn"`

	// Title is the document title.
	Title string `json:"title"`

	// Content is the document body text.
	Content string `json:"content,omitempty"`

	// Status is the publication state: PUBLISHED or UNPUBLISHED.
	Status string `json:"status,omitempty"`

	// SubType is the document sub-type classification.
	SubType string `json:"sub_type,omitempty"`

	// Source describes where the document originated.
	Source *DocumentSource `json:"source,omitempty"`

	// Settings contains visibility and behavior settings.
	Settings *DocumentSettings `json:"settings,omitempty"`

	// RelatedAssets lists the data entities linked to this document.
	RelatedAssets []DocumentRelatedAsset `json:"related_assets,omitempty"`

	// RelatedDocuments lists other documents linked to this document.
	RelatedDocuments []DocumentRelatedDocument `json:"related_documents,omitempty"`

	// ParentDocument is the parent document in a hierarchy.
	ParentDocument *DocumentParent `json:"parent_document,omitempty"`

	// Owners lists the document owners.
	Owners []Owner `json:"owners,omitempty"`

	// Tags lists tags applied to this document.
	Tags []Tag `json:"tags,omitempty"`

	// GlossaryTerms lists glossary terms associated with this document.
	GlossaryTerms []GlossaryTerm `json:"glossary_terms,omitempty"`

	// Domain is the data domain this document belongs to.
	Domain *Domain `json:"domain,omitempty"`

	// Created is the creation timestamp (epoch ms).
	Created int64 `json:"created,omitempty"`

	// LastModified is the last modification timestamp (epoch ms).
	LastModified int64 `json:"last_modified,omitempty"`
}

type DocumentParent struct {
	// URN is the parent document URN.
	URN string `json:"urn"`
}

type DocumentRelatedAsset struct {
	// URN is the data entity URN.
	URN string `json:"urn"`
}

type DocumentRelatedDocument struct {
	// URN is the related document URN.
	URN string `json:"urn"`
}

type DocumentSettings struct {
	// ShowInGlobalContext controls whether the document appears in global search.
	// When false, the document is only accessible through linked assets.
	ShowInGlobalContext bool `json:"show_in_global_context"`
}

type DocumentSource struct {
	// SourceType is NATIVE or EXTERNAL.
	SourceType string `json:"source_type"`

	// ExternalURL is the URL for external documents (Confluence, Notion, etc.).
	ExternalURL string `json:"external_url,omitempty"`
}

type Domain struct {
	// URN is the unique identifier.
	URN string `json:"urn"`

	// Name is the domain name.
	Name string `json:"name"`

	// Description is the domain description.
	Description string `json:"description,omitempty"`

	// ParentDomain is the parent domain URN.
	ParentDomain string `json:"parent_domain,omitempty"`

	// Owners are the domain owners.
	Owners []Owner `json:"owners,omitempty"`

	// EntityCount is the number of entities in this domain.
	EntityCount int `json:"entity_count,omitempty"`
}

type Entity struct {
	// URN is the unique identifier for this entity.
	URN string `json:"urn"`

	// Type is the entity type (dataset, dashboard, dataFlow, etc.).
	Type string `json:"type"`

	// Name is the display name of the entity.
	Name string `json:"name"`

	// Description is the business description.
	Description string `json:"description,omitempty"`

	// Owners lists the owners of this entity.
	Owners []Owner `json:"owners,omitempty"`

	// Tags lists the tags applied to this entity.
	Tags []Tag `json:"tags,omitempty"`

	// GlossaryTerms lists the glossary terms associated with this entity.
	GlossaryTerms []GlossaryTerm `json:"glossary_terms,omitempty"`

	// Domain is the data domain this entity belongs to.
	Domain *Domain `json:"domain,omitempty"`

	// Platform is the data platform (for datasets).
	Platform string `json:"platform,omitempty"`

	// SubTypes contains sub-type classifications (e.g., "table", "view" for datasets).
	SubTypes []string `json:"sub_types,omitempty"`

	// Deprecation contains deprecation info if the entity is deprecated.
	Deprecation *Deprecation `json:"deprecation,omitempty"`

	// Properties contains additional entity-specific properties.
	Properties map[string]any `json:"properties,omitempty"`

	// StructuredProperties contains typed structured property values (DataHub 1.3.x+).
	// Nil when the feature is unavailable or not configured.
	StructuredProperties []StructuredPropertyValue `json:"structured_properties,omitempty"`

	// ActiveIncidents contains active incidents on this entity (DataHub 1.3.x+).
	// Nil when the feature is unavailable or not configured.
	ActiveIncidents *IncidentResult `json:"active_incidents,omitempty"`

	// DataContract contains the data contract status (DataHub 1.3.x+, datasets only).
	// Nil when unavailable or for non-dataset entities.
	DataContract *DataContract `json:"data_contract,omitempty"`

	// RelatedDocuments contains context documents linked to this entity (DataHub 1.4.x+).
	// Nil when running against DataHub < 1.4.x or when no documents are linked.
	RelatedDocuments []Document `json:"related_documents,omitempty"`

	// Created is the creation timestamp.
	Created int64 `json:"created,omitempty"`

	// LastModified is the last modification timestamp.
	LastModified int64 `json:"last_modified,omitempty"`
}

type ForeignKey struct {
	// Name is the constraint name.
	Name string `json:"name,omitempty"`

	// SourceFields are the source field paths.
	SourceFields []string `json:"source_fields"`

	// ForeignDataset is the referenced dataset URN.
	ForeignDataset string `json:"foreign_dataset"`

	// ForeignFields are the referenced field paths.
	ForeignFields []string `json:"foreign_fields"`
}

type GlossaryTerm struct {
	// URN is the unique identifier.
	URN string `json:"urn"`

	// Name is the term name.
	Name string `json:"name"`

	// Description is the term definition.
	Description string `json:"description,omitempty"`

	// ParentNode is the parent glossary node URN.
	ParentNode string `json:"parent_node,omitempty"`

	// Owners are the term owners.
	Owners []Owner `json:"owners,omitempty"`

	// RelatedTerms are related glossary terms.
	RelatedTerms []GlossaryTermRelation `json:"related_terms,omitempty"`

	// Properties contains custom properties.
	Properties map[string]string `json:"properties,omitempty"`
}

type GlossaryTermRelation struct {
	// URN is the related term URN.
	URN string `json:"urn"`

	// Name is the related term name.
	Name string `json:"name"`

	// RelationType is the type of relationship.
	RelationType string `json:"relation_type"`
}

type Incident struct {
	// URN is the unique identifier for this incident.
	URN string `json:"urn"`

	// Type is the incident type (e.g., "OPERATIONAL", "CUSTOM").
	Type string `json:"type"`

	// CustomType is the custom incident type when Type is "CUSTOM".
	CustomType string `json:"custom_type,omitempty"`

	// Title is the incident title.
	Title string `json:"title"`

	// Description explains the incident.
	Description string `json:"description,omitempty"`

	// State is the current status: ACTIVE or RESOLVED.
	State string `json:"state"`

	// Source describes where the incident originated (e.g., "MANUAL").
	Source string `json:"source,omitempty"`

	// Created is the creation timestamp (epoch ms).
	Created int64 `json:"created,omitempty"`

	// CreatedBy is the actor who created the incident.
	CreatedBy string `json:"created_by,omitempty"`

	// LastUpdated is the last update timestamp (epoch ms).
	LastUpdated int64 `json:"last_updated,omitempty"`

	// LastUpdatedBy is the actor who last updated the incident.
	LastUpdatedBy string `json:"last_updated_by,omitempty"`
}

type IncidentResult struct {
	// Total is the total number of matching incidents.
	Total int `json:"total"`

	// Incidents is the list of incidents.
	Incidents []Incident `json:"incidents"`
}

type LineageEdge struct {
	// Source is the source entity URN.
	Source string `json:"source"`

	// Target is the target entity URN.
	Target string `json:"target"`

	// Type is the relationship type.
	Type string `json:"type,omitempty"`

	// Created is when the relationship was created.
	Created int64 `json:"created,omitempty"`

	// UpdatedBy is who created/updated the relationship.
	UpdatedBy string `json:"updated_by,omitempty"`

	// Properties contains additional edge properties.
	Properties map[string]any `json:"properties,omitempty"`
}

type LineageNode struct {
	// URN is the unique identifier.
	URN string `json:"urn"`

	// Type is the entity type.
	Type string `json:"type"`

	// Name is the display name.
	Name string `json:"name"`

	// Platform is the data platform.
	Platform string `json:"platform,omitempty"`

	// Description is the entity description.
	Description string `json:"description,omitempty"`

	// Level is the distance from the start node.
	Level int `json:"level"`
}

type LineageResult struct {
	// Start is the URN of the entity we queried lineage for.
	Start string `json:"start"`

	// Nodes are the entities in the lineage graph.
	Nodes []LineageNode `json:"nodes"`

	// Edges are the relationships between nodes.
	Edges []LineageEdge `json:"edges"`

	// Direction is the lineage direction (UPSTREAM or DOWNSTREAM).
	Direction string `json:"direction"`

	// Depth is the depth of the lineage traversal.
	Depth int `json:"depth"`
}

type MatchedField struct {
	// Name is the field name.
	Name string `json:"name"`

	// Value is the matched value.
	Value string `json:"value"`
}

type Owner struct {
	// URN is the owner's URN (corpuser or corpGroup).
	URN string `json:"urn"`

	// Type is the ownership type.
	Type OwnershipType `json:"type"`

	// Name is the owner's display name.
	Name string `json:"name,omitempty"`

	// Email is the owner's email address.
	Email string `json:"email,omitempty"`
}

type OwnershipType string

type ParsedURN struct {
	// Raw is the original URN string.
	Raw string `json:"raw"`

	// EntityType is the type of entity (dataset, dashboard, dataFlow, etc.).
	EntityType string `json:"entity_type"`

	// Platform is the data platform (snowflake, bigquery, postgres, etc.).
	Platform string `json:"platform,omitempty"`

	// Name is the qualified name of the entity.
	Name string `json:"name"`

	// Env is the environment (PROD, DEV, etc.).
	Env string `json:"env,omitempty"`
}

type Pipeline struct {
	Entity

	// DataFlow is the parent data flow URN.
	DataFlow string `json:"data_flow,omitempty"`

	// Inputs are the input dataset URNs.
	Inputs []string `json:"inputs,omitempty"`

	// Outputs are the output dataset URNs.
	Outputs []string `json:"outputs,omitempty"`
}

type Query struct {
	// URN is the query URN.
	URN string `json:"urn,omitempty"`

	// Name is the query name.
	Name string `json:"name,omitempty"`

	// Statement is the SQL query text.
	Statement string `json:"statement"`

	// Description is the query description.
	Description string `json:"description,omitempty"`

	// Source indicates how the query was created (e.g., "MANUAL", "SYSTEM").
	Source string `json:"source,omitempty"`

	// CreatedBy is who created the query.
	CreatedBy string `json:"created_by,omitempty"`

	// Created is when the query was created.
	Created int64 `json:"created,omitempty"`

	// LastRun is when the query was last executed.
	LastRun int64 `json:"last_run,omitempty"`

	// RunCount is how many times the query has been run.
	RunCount int `json:"run_count,omitempty"`
}

type QueryList struct {
	// Queries is the list of queries.
	Queries []Query `json:"queries"`

	// Total is the total number of queries.
	Total int `json:"total"`
}

type RaiseIncidentInput struct {
	// Type is the incident type (e.g., "OPERATIONAL").
	Type string `json:"type"`

	// CustomType is the custom incident type when Type is "CUSTOM".
	CustomType string `json:"custom_type,omitempty"`

	// Title is the incident title.
	Title string `json:"title"`

	// Description explains the incident.
	Description string `json:"description,omitempty"`

	// Priority is the incident priority: LOW, MEDIUM, HIGH, CRITICAL.
	Priority string `json:"priority,omitempty"`

	// ResourceURNs are the entity URNs affected by this incident.
	ResourceURNs []string `json:"resource_urns"`
}

type SchemaField struct {
	// FieldPath is the full path to this field (e.g., "user.address.city").
	FieldPath string `json:"field_path"`

	// Type is the field's data type.
	Type string `json:"type"`

	// NativeType is the platform-specific type.
	NativeType string `json:"native_type,omitempty"`

	// Description is the field description.
	Description string `json:"description,omitempty"`

	// Nullable indicates if the field can be null.
	Nullable bool `json:"nullable"`

	// IsPartitionKey indicates if this is a partition key.
	IsPartitionKey bool `json:"is_partition_key,omitempty"`

	// Tags lists the tags applied to this field.
	Tags []Tag `json:"tags,omitempty"`

	// GlossaryTerms lists glossary terms for this field.
	GlossaryTerms []GlossaryTerm `json:"glossary_terms,omitempty"`

	// JSONPath is the JSON path for nested fields.
	JSONPath string `json:"json_path,omitempty"`
}

type SchemaMetadata struct {
	// Name is the schema name.
	Name string `json:"name,omitempty"`

	// PlatformSchema is the platform-specific schema representation.
	PlatformSchema string `json:"platform_schema,omitempty"`

	// Version is the schema version.
	Version int64 `json:"version,omitempty"`

	// Fields is the list of schema fields.
	Fields []SchemaField `json:"fields"`

	// PrimaryKeys lists the primary key field paths.
	PrimaryKeys []string `json:"primary_keys,omitempty"`

	// ForeignKeys lists foreign key relationships.
	ForeignKeys []ForeignKey `json:"foreign_keys,omitempty"`

	// Hash is the schema hash for change detection.
	Hash string `json:"hash,omitempty"`
}

type SearchEntity struct {
	// URN is the unique identifier.
	URN string `json:"urn"`

	// Type is the entity type.
	Type string `json:"type"`

	// Name is the display name.
	Name string `json:"name"`

	// Description is the entity description.
	Description string `json:"description,omitempty"`

	// Platform is the data platform.
	Platform string `json:"platform,omitempty"`

	// Owners are the entity owners.
	Owners []Owner `json:"owners,omitempty"`

	// Tags are the entity tags.
	Tags []Tag `json:"tags,omitempty"`

	// Domain is the entity domain.
	Domain *Domain `json:"domain,omitempty"`

	// MatchedFields shows which fields matched the query.
	MatchedFields []MatchedField `json:"matched_fields,omitempty"`
}

type SearchResult struct {
	// Entities is the list of matching entities.
	Entities []SearchEntity `json:"entities"`

	// Total is the total number of matches.
	Total int `json:"total"`

	// Offset is the result offset.
	Offset int `json:"offset"`

	// Limit is the result limit.
	Limit int `json:"limit"`
}

type StructuredPropertyDefinition struct {
	// URN is the unique identifier for this structured property definition.
	URN string `json:"urn"`

	// QualifiedName is the fully qualified property name (e.g., "io.acryl.privacy.retentionTime").
	QualifiedName string `json:"qualified_name"`

	// DisplayName is the human-readable name shown in the UI.
	DisplayName string `json:"display_name,omitempty"`

	// Description explains the purpose and usage of this property.
	Description string `json:"description,omitempty"`

	// ValueType is the data type for values (e.g., "string", "number", "date", "urn").
	ValueType string `json:"value_type"`

	// Cardinality indicates whether the property accepts a single value or multiple.
	// Values: "SINGLE", "MULTIPLE".
	Cardinality string `json:"cardinality,omitempty"`

	// EntityTypes lists which entity types this property can be applied to.
	EntityTypes []string `json:"entity_types,omitempty"`

	// AllowedValues constrains the set of valid values when defined.
	AllowedValues []AllowedValue `json:"allowed_values,omitempty"`
}

type StructuredPropertyInput struct {
	// PropertyURN is the URN of the structured property definition.
	PropertyURN string

	// Values holds the value(s) to assign. Elements should be strings or numbers.
	Values []any
}

type StructuredPropertyValue struct {
	// PropertyURN identifies which structured property definition this value belongs to.
	PropertyURN string `json:"property_urn"`

	// Definition contains the full property definition, when available.
	Definition *StructuredPropertyDefinition `json:"definition,omitempty"`

	// Values holds the assigned value(s). Elements are typically strings or numbers.
	Values []any `json:"values"`
}

type Tag struct {
	// URN is the unique identifier.
	URN string `json:"urn"`

	// Name is the tag name.
	Name string `json:"name"`

	// Description is the tag description.
	Description string `json:"description,omitempty"`

	// Properties contains custom properties.
	Properties map[string]string `json:"properties,omitempty"`
}

type UpdateIncidentInput struct {
	// Title is the updated title (empty means no change).
	Title string

	// Description is the updated description (empty means no change).
	Description string

	// Priority is the updated priority (empty means no change).
	// Values: LOW, MEDIUM, HIGH, CRITICAL.
	Priority string
}

type UpdateStructuredPropertyInput struct {
	// DisplayName is the updated human-readable name.
	DisplayName string

	// Description is the updated description.
	Description string

	// NewAllowedValues are additional allowed values to add.
	NewAllowedValues []AllowedValue
}

type UpsertDataContractInput struct {
	// DatasetURN is the dataset to apply the contract to (required).
	DatasetURN string

	// SchemaAssertionURNs are assertion URNs for schema validation.
	SchemaAssertionURNs []string

	// FreshnessAssertionURNs are assertion URNs for freshness validation.
	FreshnessAssertionURNs []string

	// DataQualityAssertionURNs are assertion URNs for data quality validation.
	DataQualityAssertionURNs []string
}