reconciler

Documentation

Overview

package reconciler describes entities for implementation of a Reconciliation Service API v0.2 https://www.w3.org/community/reports/reconciliation/CG-FINAL-specs-0.2-20230410/

Index

• type Choice
• type Entity
• type Extend
• type ExtendOutput
• type ExtendQuery
• type Feature
• type Input
• type Manifest
• type Output
• type Preview
• type Property
• type PropertyInfo
• type PropertyOutput
• type PropertySetting
• type PropertyValue
• type ProposeProperties
• type Query
• type ReconciliationCandidate
• type ReconciliationResult
• type Type
• type View

Types

type Choice

type Choice struct {
	ID    string `json:"id"`
	Value string `json:"value"`
}

Choice provides flexibility to PropertySetting, allowing several different variants.

type Entity

type Entity struct {
	// ID of an entity.
	ID string `json:"id"`

	// Name is a human-friendly title for an entity.
	Name string `json:"string"`

	// Description explains what an entity is.
	Description string `json:"description"`

	// Type or types of an entity.
	Type []Type `json:"type"`
}

Entity describes an entity that can be used during reconciliation.

type Extend

type Extend struct {
	// ProposeProperties contains metadata for Extend service.
	ProposeProperties `json:"propose_properties,omitempty"`

	// PropertySettings (optional) describes existing properties.
	PropertySettings []PropertySetting `json:"property_settings"`
}

Extend provides information about optional additional information connected to the reconciliation candidate.

type ExtendOutput

type ExtendOutput struct {
	// Meta describes properties information.
	Meta []Property `json:"meta"`

	// Rows is a map, where the key is an entity ID, and the value is another
	// map where key is the property ID, and the value is a slice of property
	// values (for simplification values are always JSON-encoded strings).
	Rows map[string]map[string][]PropertyValue `json:"rows"`
}

ExtendOutput provides data returned by Extend query.

type ExtendQuery

type ExtendQuery struct {
	//IDs contain an entity IDs.
	IDs []string `json:"ids"`

	// Properties contains a slice of properties.
	Properties []Property `json:"properties"`
}

ExtendQuery provides input for getting additional properties associated with the name-string ID.

type Feature

type Feature struct {
	// ID is the name of the feature.
	ID string `json:"id"`

	// Value is a quantitative representation of the feature.
	Value float64 `json:"value"`
}

Feature is a matching feature that can be used to determing the matching score.

type Input

type Input struct {
	// Queries contains all requested queries. Queries are identified
	// by an identification string.
	Queries map[string]Query `form:"queries"`
}

Input contains fields necessary for the reconciliation process. This intput is compatible with W3C Reconciliation API.

type Manifest

type Manifest struct {
	// Versions returns the versions of W3C Reconciliation API descrived at
	// https://www.w3.org/community/reports/reconciliation/CG-FINAL-specs-0.2-20230410 .
	// Versions can have "1.0" and "2.0" elements. For our purposes
	// it should be set to ["2.0"].
	Versions []string `json:"versions"`

	// Name of the reconciliation service. Should be set to "GlobalNames".
	Name string `json:"name"`

	Preview `json:"preview"`
	View    `json:"view"`

	Extend `json:"extend"`

	// IdentifierSpace contans the URI prefix of the reconciliation service.
	// For example "https://verifier.globalnames.org/api/v1/name_strings/"
	IdentifierSpace string `json:"identifierSpace"`

	// SchemaSpace provides the URL pointing to the schema of an entity.
	SchemaSpace string `json:"schemaSpace"`

	// DefaultTypes used for a reconciliation queries.
	DefaultTypes []Type `json:"defaultTypes"`

	// BatchSize sets maximum amount of queris in one batch.
	BatchSize int
}

Manifest describes metadata of a W3C Reconciliation Service.

type Output

type Output map[string]ReconciliationResult

Ouput is a map where the key is the provided identifier of a query, and the ReconciliationResult contains all found ReconciliationCandidates.

type Preview

type Preview struct {
	// Height is the vertical size of a widget in pixels.
	Height int `json:"height"`

	// Width is a horisontal size of a widget in pixels.
	Width int `json:"width"`

	// URL provides a template in a form of `https://host/path/{{id}}`
	// where '{{id}}' will be substituted with an Entity ID
	URL string `json:"url"`
}

Preview sets options to provide a widget with more details about a reconciliation candidate.

type Property

type Property struct {
	// ID is a property identifier.
	ID string `json:"id"`

	// Name is human-friendly title of a property.
	Name string `json:"name"`
}

Property implements the APIs `property`, an attribute of an entity.

type PropertyInfo

type PropertyInfo struct {
	// PropertyID is the same as Property.ID
	PropertyID string `json:"pid"`

	// PropertyValue is the value of PropertyValue.Str for this property.
	PropertyValue string `json:"v"`
}

PropertyInfo combines a property ID with the value of the property. PropertyInfo can be used to further filter list of candidates, similar to a WHERE cause in SQL. This implementation is less flexible than W3C standard and takes only one value. We will expand it if necessary.

type PropertyOutput

type PropertyOutput struct {
	// Type is the type ID for a given entity type.
	Type string `json:"type"`

	// Properties describes corresponding properties of the type.
	Properties []Property `json:"properties"`
}

PropertyOutput provides information about properties known for a particular `entity` type.

type PropertySetting

type PropertySetting struct {
	// Name of the property settings.
	Name string `json:"name"`

	// Label of the property settings.
	Label string `json:"label"`

	// Type of the property settings.
	Type string `json:"type"`

	// Default value of the property settings.
	Default string `json:"default"`

	// HelpText explains the property setting.
	HelpText string `json:"help_text,omitempty"`

	// Choices for the setting (optional)
	Choices []Choice `json:"choices,omitempty"`
}

PropertySetting provides metadata of optional property settings for defining properties in Extend queries.

type PropertyValue

type PropertyValue struct {
	Str string `json:"str"`
}

PropertyValue is simplified compare to API, for now it supports only a string value.

type ProposeProperties

type ProposeProperties struct {
	// ServiceURL contains Extend service URL without a path.
	ServiceURL string `json:"service_url,omitempty"`

	// ServicePath is the path part of the Extend service.
	ServicePath string `json:"service_path"`
}

ProposeProperties provides metadata for Extend service.

type Query

type Query struct {
	// Query contains a name-string we try to reconcile.
	Query string `json:"query"`

	// Type allows to constrain reconciliation agains specific type described
	// in the manifest.
	Type string `json:"type"`

	// Limit restricts the number of candidates returned by the query.
	Limit int `json:"limit"`

	// Properties allow to add additional filters to the reconciliation
	// process.
	Properties []PropertyInfo `json:"properties,omitempty"`

	// TypeStrict is a legacy deprecated field that came from FreeBase.
	TypeStrict string `json:"type_strict,omitempty"`
}

Query is a set of fields used for verification.

type ReconciliationCandidate

type ReconciliationCandidate struct {
	// ID can be used to lookup the entity in a corresponding service.
	ID string `json:"id"`

	// Name contains reconciled name-string.
	Name string `json:"name"`

	// Description provides some metadata about the item.
	Description string `json:"description"`

	// Score is used to estimate chances for a result to be a match.
	// It is calculated from features.
	Score float64 `json:"score"`

	// Features might contain details of reconciliation and be used for
	// the score calculation.
	Features []Feature `json:"features,omitempty"`

	// Types contains types that were assigned to the candidate.
	Types []Type `json:"types"`

	// Match is true if the score is above a threshold and without a
	// reasonable doubt the result is the best match to the query.
	Match bool `json:"match"`
}

ReconciliationCandidate contains the details of a reconciliation item.

type ReconciliationResult

type ReconciliationResult struct {
	// Result contains all candidates for reconciliation.
	Result []ReconciliationCandidate `json:"result"`
}

ReconciliationResult is a slice where results are sorted by their score.

type Type

type Type struct {
	// ID is a unique identifier for the type.
	ID string `json:"id"`

	// Name is a human friendly short description of the type.
	Name string `json:"name"`
}

Type describes types available for the reconciliation service.

type View

type View struct {
	// URL provides a template in a form of `http://host/path{{id}}`.
	// This URL is an outlink to an entity with the given ID.
	URL string `json:"url"`
}

View provides options for outlink where it shows details about a reconciliation candidate on a remote web page.