xsd

Documentation

Overview

Package xsd parses type declarations in XML Schema documents.

The xsd package implements a parser for a subset of the XML Schema standard. This package is intended for use in code-generation programs for client libraries, and as such, does not validate XML Schema documents, nor does it provide sufficient information to validate the documents described by a schema. Notably, the xsd package does not preserve information about element or attribute groups. Instead, all groups are de-referenced before parsing is done, and all nested sequences of elements are flattened.

The xsd package respects XML name spaces in schema documents, and can parse schema documents that import or include other schema documents.

Index

• Variables
• func Normalize(docs ...[]byte) ([]*xmltree.Element, error)
• func XMLName(t Type) xml.Name
• type Attribute
• type Builtin
  • func ParseBuiltin(qname xml.Name) (Builtin, error)
  • func (b Builtin) Name() xml.Name
  • func (i Builtin) String() string
• type ComplexType
• type Element
• type Ref
  • func Imports(data []byte) ([]Ref, error)
• type Restriction
• type Schema
  • func Parse(docs ...[]byte) ([]Schema, error)
  • func (s *Schema) FindType(name xml.Name) Type
• type SimpleType
• type Type
  • func Base(t Type) Type

Variables

var StandardSchema = [][]byte{
	soapenc11xsd,
	xmlnsxsd,
	wsdl2003xsd,
	xlinkxsd,
}

The xsd package bundles a number of well-known schemas. These schemas are always added to the list of available schema when parsing an XML schema using the Parse function.

Functions

func Normalize

func Normalize(docs ...[]byte) ([]*xmltree.Element, error)

Normalize reads XML schema documents and returns xml trees for each schema with the following properties:

• various XSD shorthand, such as omitting <complexContent>, are expanded into their canonical forms.
• all links are dereferenced by merging the linked element.
• all types have names. For anonymous types, unique (per namespace) names of the form "_anon1", "_anon2", etc are generated, and the attribute "_isAnonymous" is set to "true".

Because one document may contain more than one schema, the number of trees returned by Normalize may not equal the number of arguments.

func XMLName

func XMLName(t Type) xml.Name

XMLName returns the canonical xml name of a Type.

Types

type Attribute

type Attribute struct {
	// The canonical name of this attribute. It is uncommon for attributes
	// to have a name space.
	Name xml.Name
	// Annotation provided for this attribute by the schema author.
	Doc string
	// The type of the attribute value. Must be a simple or built-in Type.
	Type Type
	// True if this attribute has a <list> simpleType
	Plural bool
	// Default overrides the zero value of this element.
	Default string
	// True if the attribute is not required
	Optional bool
	// Any additional attributes provided in the <xs:attribute> element.
	Attr []xml.Attr
	// Used for resolving qnames in additional attributes.
	xmltree.Scope
}

An Attribute describes the key=value pairs that may appear within the opening tag of an element. Only complex types may contain attributes. the Type of an Attribute can only be a Builtin or SimpleType.

http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/structures.html#element-attribute

type Builtin

type Builtin int

A built-in represents one of the built-in xml schema types, as defined in the W3C specification, "XML Schema Part 2: Datatypes".

http://www.w3.org/TR/xmlschema-2/#built-in-datatypes

const (
	AnyType Builtin = iota
	ENTITIES
	ENTITY
	ID
	IDREF
	IDREFS
	NCName
	NMTOKEN
	NMTOKENS
	NOTATION
	Name
	QName
	AnyURI
	Base64Binary
	Boolean
	Byte
	Date
	DateTime // ISO 8601 format (similar to RFC3339)
	Decimal
	Double
	Duration
	Float
	GDay       // ---DD
	GMonth     // --MM
	GMonthDay  // --MM-DD
	GYear      // YYYY
	GYearMonth // YYYY-MM
	HexBinary
	Int
	Integer
	Language
	Long
	NegativeInteger
	NonNegativeInteger
	NonPositiveInteger
	NormalizedString
	PositiveInteger
	Short
	String
	Time
	Token
	UnsignedByte
	UnsignedInt
	UnsignedLong
	UnsignedShort
	XMLLang  // xml:lang
	XMLSpace // xml:space
	XMLBase  // xml:base
	XMLId    // xml:id
	AnySimpleType
)

func ParseBuiltin

func ParseBuiltin(qname xml.Name) (Builtin, error)

ParseBuiltin looks up a Builtin by name. If qname does not name a built-in type, ParseBuiltin returns a non-nil error.

func (Builtin) Name

func (b Builtin) Name() xml.Name

Name returns the canonical name of the built-in type. All built-in types are in the standard XML schema namespace, http://www.w3.org/2001/XMLSchema, or the XML namespace, http://www.w3.org/2009/01/xml.xsd

func (Builtin) String

func (i Builtin) String() string

type ComplexType

type ComplexType struct {
	// Annotations provided by the schema author.
	Doc string
	// The canonical name of this type.
	Name xml.Name
	// The type this type is derived from.
	Base Type
	// True if this is an anonymous type
	Anonymous bool
	// XML elements that this type may contain in its content.
	Elements []Element
	// Possible attributes for the element's opening tag.
	Attributes []Attribute
	// An abstract type does not appear in the xml document, but
	// is "implemented" by other types in its substitution group.
	Abstract bool
	// If true, this type is an extension to Base.  Otherwise,
	// this type is derived by restricting the set of elements and
	// attributes allowed in Base.
	Extends bool
	// If true, this type is allowed to contain character data that is
	// not part of any sub-element.
	Mixed bool
}

A ComplexType describes an XML element that may contain attributes and elements in its content. Complex types are derived by extending or restricting another type. The xsd package records the elements and attributes that may occur in an xml element conforming to the type. A ComplexType is part of a linked list, through its Base field, that is guaranteed to end in the Builtin value AnyType.

http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/structures.html#element-complexType

type Element

type Element struct {
	// Annotations for this element
	Doc string
	// The canonical name of this element
	Name xml.Name
	// True if this element can have any name. See
	// http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/structures.html#element-any
	Wildcard bool
	// Type of this element.
	Type Type
	// An abstract type does not appear in the xml document, but
	// is "implemented" by other types in its substitution group.
	Abstract bool
	// True if maxOccurs > 1 or maxOccurs == "unbounded"
	Plural bool
	// True if the element is optional.
	Optional bool
	// If true, this element will be declared as a pointer.
	Nillable bool
	// Default overrides the zero value of this element.
	Default string
	// Any additional attributes provided in the <xs:element> element.
	Attr []xml.Attr
	// Used for resolving prefixed strings in extra attribute values.
	xmltree.Scope
}

An Element describes an XML element that may appear as part of a complex type. Elements may have restrictions about the number of times they may appear and they values they may contain. The xsd package converts this low-level information into boolean flags where appropriate.

http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/structures.html#element-element

type Ref

type Ref struct {
	Namespace, Location string
}

A Ref contains the canonical namespace of a schema document, and possibly a URI to retrieve the document from. It is not required for XML Schema documents to provide the location of schema that they import; it is expected that all well-known schema namespaces are available to the consumer of a schema beforehand.

func Imports

func Imports(data []byte) ([]Ref, error)

Imports reads an XML document containing one or more <schema> elements and returns a list of canonical XML name spaces that the schema imports or includes, along with a URL for the schema, if provided.

type Restriction

type Restriction struct {
	// The max digits to the right of the decimal point for
	// floating-point values.
	Precision int
	// If len(Enum) > 0, the type must be one of the values contained
	// in Enum.
	Enum []string
	// The minimum and maximum (exclusive) value of this type, if
	// numeric
	Min, Max float64
	// Maximum and minimum length (in characters) of this type
	MinLength, MaxLength int
	// Regular expression that values of this type must match
	Pattern *regexp.Regexp
	// Any annotations for the restriction, if present.
	Doc string
}

A SimpleType can be derived from a built-in or SimpleType by restricting the set of values it may contain. The xsd package only records restrictions that are useful for generating client libraries, and not for validating documents.

http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html#element-restriction

type Schema

type Schema struct {
	// The Target namespace of the schema. All types defined in this
	// schema will be in this name space.
	TargetNS string `xml:"targetNamespace,attr"`
	// Types defined in this schema declaration
	Types map[xml.Name]Type
	// Any annotations declared at the top-level of the schema, separated
	// by new lines.
	Doc string
}

A Schema is the decoded form of an XSD <schema> element. It contains a collection of all types declared in the schema. Top-level elements are not recorded in a Schema.

func Parse

func Parse(docs ...[]byte) ([]Schema, error)

Parse reads XML documents containing one or more <schema> elements. The returned slice has one Schema for every <schema> element in the documents. Parse will not fetch schema used in <import> or <include> statements; use the Imports function to find any additional schema documents required for a schema.

func (*Schema) FindType

func (s *Schema) FindType(name xml.Name) Type

FindType looks for a type by its canonical name. In addition to the types declared in a Schema, FindType will also search through the types that a Schema's top-level types are derived from. FindType will return nil if a type could not be found with the given name.

type SimpleType

type SimpleType struct {
	// True if this is an anonymous type
	Anonymous bool
	// True if this type is a whitespace-delimited list, with
	// items of type Base.
	List bool
	// A simpleType may be described as a union: one of many
	// possible simpleTypes.
	Union []Type
	// Restrictions on this type's values
	Restriction Restriction
	// The canonical name of this type
	Name xml.Name
	// Any annotations for this type, as provided by the schema
	// author.
	Doc string
	// The type this type is derived from. This is guaranteed to be
	// part of a linked list that always ends in a Builtin type.
	Base Type
}

A SimpleType describes an XML element that does not contain elements or attributes. SimpleTypes are suitable for use as attribute values. A SimpleType can be an "atomic" type (int, string, etc), or a list of atomic types, separated by white space. In addition, a SimpleType may be declared as a union; or one of a set of SimpleTypes. A SimpleType is guaranteed to be part of a linked list, through its Base field, that ends in a Builtin value.

http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html#element-simpleType

http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html#element-union

http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html#element-list

type Type

type Type interface {
	// contains filtered or unexported methods
}

Types in XML Schema Documents are derived from one of the built-in types defined by the standard, by restricting or extending the range of values a type may contain. A Type may be one of *SimpleType, *ComplexType, or Builtin.

func Base

func Base(t Type) Type

Base returns the base type that a Type is derived from. If the value is of type Builtin, Base will return nil.