publiccode

README

publiccode.yml parser for Go

A Go parser and validator for publiccode.yml files.

publiccode.yml is an international standard for describing public software, which should be placed at the root of Free/Libre and Open Source software repositories.

This parser performs syntactic and semantic validation according to the official spec.

Features

• Go library and CLI tool (publiccode-parser)
• Supports the latest version of the publiccode.yml Standard
• publiccode-parser can output validation errors as JSON or in errorformat friendly way
• Verifies the existence of URLs by checking the response for URL fields (can be disabled)

Example usage as a library

parser, err := publiccode.NewDefaultParser()

// error handling

publiccode, err := parser.Parse("file:///path/to/local/dir/publiccode.yml")
// OR
// parse.Parse("https://github.com/example/example/publiccode.yml")

Validation from command line

The publiccode-parser binary which be used for validating a publiccode.yml from the command line.

To get the latest development version use:

go install github.com/italia/publiccode-parser-go/v4/publiccode-parser@latest
publiccode-parser mypubliccode.yml

To get the latest stable version go to the release page and grab the one for your arch.

Run publiccode-parser --help for the available command line flags.

The tool returns 0 in case of successful validation, 1 otherwise.

Easy validation with Docker

You can easily validate your files using Docker on your local machine or in your CI pipeline:

docker run -i italia/publiccode-parser-go /dev/stdin < publiccode.yml

The image is available on Dockerhub. You can also build your own running:

docker build -t italia/publiccode-parser-go .

Examples

The examples assume that your publiccode.yml file is on your local machine, at /home/my-user/publiccodes/publiccode.yml

• Validate and print the canonicalized file

  docker run -i italia/publiccode-parser-go -export /dev/stdout /dev/stdin < publiccode.yml
  

• Validate a publiccode file named publiccode.yml in /home/user

  docker run -v /home/user:/go/src/files italia/publiccode-parser-go
  

• Validate a publiccode file named /opt/publiccodes/my-amazing-code.yaml

  docker run -v /opt/publiccodes:/go/src/files italia/publiccode-parser-go my-amazing-code.yaml
  

• Validate publiccode.yml without using the network (fe. checking URLs are reachable)

  docker run -v /opt/publiccodes/publiccodes:/files italia/publiccode-parser-go -no-network publiccode.yml
  

• Debugging, access the container interactive shell, overriding the entrypoint

  docker run -it --entrypoint /bin/sh italia/publiccode-parser-go
  

Contributing

Contributing is always appreciated. Feel free to open issues, fork or submit a Pull Request. If you want to know more about how to add new fields, check out CONTRIBUTING.md. In order to support other country-specific extensions in addition to Italy some refactoring might be needed.

See also

• publiccode-crawler - a Go crawler that uses this library

Maintainers

This software is maintained by the Developers Italia team.

License

© 2018-present Team per la Trasformazione Digitale - Presidenza del Consiglio dei Ministri

Licensed under the EUPL 1.2. The version control system provides attribution for specific lines of code.

Documentation

Index

• Variables
• type ContactV0
• type ContractorV0
• type DependencyV0
• type DescV0
• type Domain
• type ITSectionV0
• type ParseError
  • func (e ParseError) Error() string
• type Parser
  • func NewDefaultParser() (*Parser, error)
  • func NewParser(config ParserConfig) (*Parser, error)
  • func (p *Parser) Parse(uri string) (PublicCode, error)
  • func (p *Parser) ParseStream(in io.Reader) (PublicCode, error)
• type ParserConfig
• type PublicCode
• type PublicCodeV0
  • func (p PublicCodeV0) ToYAML() ([]byte, error)
  • func (p PublicCodeV0) Url() *URL
  • func (p PublicCodeV0) Version() uint
• type URL
  • func (u *URL) MarshalYAML() (interface{}, error)
  • func (u URL) String() string
  • func (u *URL) UnmarshalYAML(unmarshal func(interface{}) error) error
• type UrlOrUrlArray
  • func (a *UrlOrUrlArray) UnmarshalYAML(unmarshal func(interface{}) error) error
• type ValidationError
  • func (e ValidationError) Error() string
  • func (e ValidationError) MarshalJSON() ([]byte, error)
• type ValidationResults
  • func (vr ValidationResults) Error() string
• type ValidationWarning
  • func (e ValidationWarning) Error() string
  • func (e ValidationWarning) MarshalJSON() ([]byte, error)

Variables

var SupportedVersions = []string{"0.2", "0.2.0", "0.2.1", "0.2.2", "0.3", "0.3.0", "0.4", "0.4.0"}

SupportedVersions lists the publiccode.yml versions this parser supports.

Types

type ContactV0

type ContactV0 struct {
	Name        string  `yaml:"name" validate:"required"`
	Email       *string `yaml:"email,omitempty" validate:"omitempty,email"`
	Affiliation *string `yaml:"affiliation,omitempty"`
	Phone       *string `yaml:"phone,omitempty" validate:"omitempty"`
}

ContactV0 is a contact info maintaining the software.

type ContractorV0

type ContractorV0 struct {
	Name    string  `yaml:"name" validate:"required"`
	Email   *string `yaml:"email,omitempty" validate:"omitempty,email"`
	Website *URL    `yaml:"website,omitempty" validate:"omitnil,url_http_url"`
	Until   string  `yaml:"until" validate:"required,date"`
}

ContractorV0 is an entity or entities, if any, that are currently contracted for maintaining the software.

type DependencyV0

type DependencyV0 struct {
	Name       string  `yaml:"name" validate:"required,gt=0"`
	VersionMin *string `yaml:"versionMin,omitempty"`
	VersionMax *string `yaml:"versionMax,omitempty"`
	Optional   *bool   `yaml:"optional,omitempty"`
	Version    *string `yaml:"version,omitempty"`
}

DependencyV0 describes system-level dependencies required to install and use this software.

type DescV0

type DescV0 struct {
	LocalisedName    *string   `yaml:"localisedName,omitempty"`
	GenericName      string    `yaml:"genericName" validate:"umax=35"`
	ShortDescription string    `yaml:"shortDescription" validate:"required,umax=150"`
	LongDescription  string    `yaml:"longDescription,omitempty" validate:"required,umin=150,umax=10000"`
	Documentation    *URL      `yaml:"documentation,omitempty" validate:"omitnil,url_http_url"`
	APIDocumentation *URL      `yaml:"apiDocumentation,omitempty" validate:"omitnil,url_http_url"`
	Features         *[]string `yaml:"features,omitempty" validate:"gt=0,dive"`
	Screenshots      []string  `yaml:"screenshots,omitempty"`
	Videos           []*URL    `yaml:"videos,omitempty" validate:"dive,omitnil,url_http_url"`
	Awards           []string  `yaml:"awards,omitempty"`
}

DescV0 is a general description of the software.

type Domain

type Domain struct {
	// Domains.yml data
	Host        string   `yaml:"host"`
	UseTokenFor []string `yaml:"use-token-for"`
	BasicAuth   []string `yaml:"basic-auth"`
}

Domain is a single code hosting service.

type ITSectionV0

type ITSectionV0 struct {
	CountryExtensionVersion *string `yaml:"countryExtensionVersion" validate:"omitnil,oneof=0.2 1.0"`

	Conforme struct {
		LineeGuidaDesign        bool `yaml:"lineeGuidaDesign,omitempty"`
		ModelloInteroperabilita bool `yaml:"modelloInteroperabilita"`
		MisureMinimeSicurezza   bool `yaml:"misureMinimeSicurezza"`
		GDPR                    bool `yaml:"gdpr"`
	} `yaml:"conforme"`

	Riuso struct {
		CodiceIPA string `yaml:"codiceIPA,omitempty" validate:"omitempty,is_italian_ipa_code"`
	} `yaml:"riuso,omitempty"`

	Piattaforme struct {
		SPID   bool `yaml:"spid"`
		PagoPa bool `yaml:"pagopa"`
		CIE    bool `yaml:"cie"`
		ANPR   bool `yaml:"anpr"`
		Io     bool `yaml:"io"`
	} `yaml:"piattaforme"`
}

type ParseError

type ParseError struct {
	Reason string
}

A generic parse error.

func (ParseError) Error

func (e ParseError) Error() string

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser is a helper class for parsing publiccode.yml files.

func NewDefaultParser

func NewDefaultParser() (*Parser, error)

func NewParser

func NewParser(config ParserConfig) (*Parser, error)

NewParser initializes and returns a new Parser object following the settings in ParserConfig.

func (*Parser) Parse

func (p *Parser) Parse(uri string) (PublicCode, error)

func (*Parser) ParseStream

func (p *Parser) ParseStream(in io.Reader) (PublicCode, error)

ParseStream reads the data and tries to parse it. Returns an error if fails.

type ParserConfig

type ParserConfig struct {
	// DisableNetwork disables all network tests (URL existence and Oembed). This
	// results in much faster parsing.
	DisableNetwork bool

	// Domain will have domain specific settings, including basic auth if provided
	// this will avoid strong quota limit imposed by code hosting platform
	Domain Domain

	// The name of the branch used to check for existence of the files referenced
	// in the publiccode.yml
	Branch string

	// The URL used as base of relative files in publiccode.yml (eg. logo)
	// It can be a local file with the 'file' scheme.
	BaseURL string
}

type PublicCode

type PublicCode interface {
	Version() uint
	Url() *URL
	ToYAML() ([]byte, error)
}

type PublicCodeV0

type PublicCodeV0 struct {
	PubliccodeYamlVersion string `yaml:"publiccodeYmlVersion" validate:"required,oneof=0.2 0.2.0 0.2.1 0.2.2 0.3 0.3.0 0.4 0.4.0"`

	Name             string `yaml:"name" validate:"required"`
	ApplicationSuite string `yaml:"applicationSuite,omitempty"`
	URL              *URL   `yaml:"url" validate:"required,url_url"`
	LandingURL       *URL   `yaml:"landingURL,omitempty" validate:"omitnil,url_http_url"`

	IsBasedOn       UrlOrUrlArray `yaml:"isBasedOn,omitempty"`
	SoftwareVersion string        `yaml:"softwareVersion,omitempty"`
	ReleaseDate     *string       `yaml:"releaseDate" validate:"omitnil,date"`
	Logo            string        `yaml:"logo,omitempty"`
	MonochromeLogo  string        `yaml:"monochromeLogo,omitempty"`

	InputTypes  []string `yaml:"inputTypes,omitempty"`
	OutputTypes []string `yaml:"outputTypes,omitempty"`

	Platforms []string `yaml:"platforms" validate:"gt=0"`

	Categories []string `yaml:"categories" validate:"required,gt=0,dive,is_category_v0"`

	UsedBy *[]string `yaml:"usedBy,omitempty"`

	Roadmap *URL `yaml:"roadmap,omitempty" validate:"omitnil,url_http_url"`

	DevelopmentStatus string `yaml:"developmentStatus" validate:"required,oneof=concept development beta stable obsolete"`

	SoftwareType string `` /* 181-byte string literal not displayed */

	IntendedAudience *struct {
		Scope                *[]string `yaml:"scope,omitempty" validate:"omitempty,dive,is_scope_v0"`
		Countries            *[]string `yaml:"countries,omitempty" validate:"omitempty,dive,iso3166_1_alpha2_lowercase"`
		UnsupportedCountries *[]string `yaml:"unsupportedCountries,omitempty" validate:"omitempty,dive,iso3166_1_alpha2_lowercase"`
	} `yaml:"intendedAudience,omitempty"`

	Description map[string]DescV0 `yaml:"description" validate:"gt=0,bcp47_keys,dive"`

	Legal struct {
		License            string  `yaml:"license" validate:"required"`
		MainCopyrightOwner *string `yaml:"mainCopyrightOwner,omitempty"`
		RepoOwner          *string `yaml:"repoOwner,omitempty"`
		AuthorsFile        *string `yaml:"authorsFile,omitempty"`
	} `yaml:"legal"`

	Maintenance struct {
		Type        string         `yaml:"type" validate:"required,oneof=internal contract community none"`
		Contractors []ContractorV0 `yaml:"contractors,omitempty" validate:"required_if=Type contract,dive"`
		Contacts    []ContactV0    `yaml:"contacts,omitempty" validate:"required_if=Type community,required_if=Type internal,dive"`
	} `yaml:"maintenance"`

	Localisation struct {
		LocalisationReady  *bool    `yaml:"localisationReady" validate:"required"`
		AvailableLanguages []string `yaml:"availableLanguages" validate:"required,gt=0,dive,bcp47_language_tag"`
	} `yaml:"localisation"`

	DependsOn *struct {
		Open        *[]DependencyV0 `yaml:"open,omitempty" validate:"omitempty,dive"`
		Proprietary *[]DependencyV0 `yaml:"proprietary,omitempty" validate:"omitempty,dive"`
		Hardware    *[]DependencyV0 `yaml:"hardware,omitempty" validate:"omitempty,dive"`
	} `yaml:"dependsOn,omitempty"`

	It ITSectionV0 `yaml:"it"`
}

PublicCodeV0 defines how a publiccode.yml v0.x is structured

func (PublicCodeV0) ToYAML

func (p PublicCodeV0) ToYAML() ([]byte, error)

func (PublicCodeV0) Url

func (p PublicCodeV0) Url() *URL

func (PublicCodeV0) Version

func (p PublicCodeV0) Version() uint

type URL

type URL url.URL

func (*URL) MarshalYAML

func (u *URL) MarshalYAML() (interface{}, error)

func (URL) String

func (u URL) String() string

func (*URL) UnmarshalYAML

func (u *URL) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements the yaml.Unmarshaler interface for URLs.

type UrlOrUrlArray

type UrlOrUrlArray []*URL

func (*UrlOrUrlArray) UnmarshalYAML

func (a *UrlOrUrlArray) UnmarshalYAML(unmarshal func(interface{}) error) error

type ValidationError

type ValidationError struct {
	Key         string `json:"key"`
	Description string `json:"description"`
	Line        int    `json:"line"`
	Column      int    `json:"column"`
}

func (ValidationError) Error

func (e ValidationError) Error() string

func (ValidationError) MarshalJSON

func (e ValidationError) MarshalJSON() ([]byte, error)

type ValidationResults

type ValidationResults []error

func (ValidationResults) Error

func (vr ValidationResults) Error() string

type ValidationWarning

type ValidationWarning ValidationError

func (ValidationWarning) Error

func (e ValidationWarning) Error() string

func (ValidationWarning) MarshalJSON

func (e ValidationWarning) MarshalJSON() ([]byte, error)