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

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

// all these settings are optional:
parser.DisableNetwork = true
parser.Branch = "mybranch"

err := parser.Parse()
publiccode := parser.PublicCode

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/v3/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

• Developers Italia backend & 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

• Constants
• Variables
• type Contact
• type Contractor
• type Dependency
• type Desc
• type Domain
• type ExtensionIT
• type ParseError
  • func (e ParseError) Error() string
• type Parser
  • func NewParser(file string) (*Parser, error)
  • func NewParserWithPath(file string, path string) (*Parser, error)
  • func (p *Parser) Parse() error
  • func (p *Parser) ParseBytes(in []byte) error
  • func (p *Parser) ParseInDomain(in []byte, host string, utf []string, ba []string) error
  • func (p *Parser) ToYAML() ([]byte, error)
• type PublicCode
• 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)

Constants

const Version = "0.3"

Version of the latest PublicCode specs.

Variables

var ExtensionITSupportedVersions = []string{"0.2"}

ExtensionITSupportedVersions declares the versions of the 'it' extension supported by this parser. We also support legacy publiccode.yml files which did not contain the it/countryExtensionVersion key.

var ExtensionITVersion = "0.2"

ExtensionITVersion declares the latest supported version of the 'it' section

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

SupportedVersions lists the publiccode.yml versions this parser supports.

Types

type Contact

type Contact 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"`
}

Contact is a contact info maintaining the software.

type Contractor

type Contractor 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"`
}

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

type Dependency

type Dependency 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"`
}

Dependency describe system-level dependencies required to install and use this software.

type Desc

type Desc 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"`
}

Desc 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 ExtensionIT

type ExtensionIT struct {
	CountryExtensionVersion string `yaml:"countryExtensionVersion"`

	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"`
}

ExtensionIT is the country-specific section for Italy.

type ParseError

type ParseError struct {
	Reason string
}

A generic parse error.

func (ParseError) Error

func (e ParseError) Error() string

type Parser

type Parser struct {
	PublicCode PublicCode

	// 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
	// contains filtered or unexported fields
}

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

func NewParser

func NewParser(file string) (*Parser, error)

NewParser initializes a new Parser object and returns it. TODO

func NewParserWithPath

func NewParserWithPath(file string, path string) (*Parser, error)

TODO doc empty string disables it and enables remote

func (*Parser) Parse

func (p *Parser) Parse() error

func (*Parser) ParseBytes

func (p *Parser) ParseBytes(in []byte) error

ParseBytes loads the yaml bytes and tries to parse it. Return an error if fails.

func (*Parser) ParseInDomain

func (p *Parser) ParseInDomain(in []byte, host string, utf []string, ba []string) error

ParseInDomain wrapper func to be in domain env

func (*Parser) ToYAML

func (p *Parser) ToYAML() ([]byte, error)

ToYAML converts parser.PublicCode into YAML again.

type PublicCode

type PublicCode struct {
	PubliccodeYamlVersion string `yaml:"publiccodeYmlVersion" validate:"required,oneof=0.2 0.2.0 0.2.1 0.2.2 0.3 0.3.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:"required,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_2"`

	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_2"`
		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]Desc `yaml:"description" validate:"gt=0,dive,keys,bcp47_language_tag,endkeys,required"`

	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" validate:"required"`

	Maintenance struct {
		Type        string       `yaml:"type" validate:"required,oneof=internal contract community none"`
		Contractors []Contractor `yaml:"contractors,omitempty" validate:"required_if=Type contract,dive"`
		Contacts    []Contact    `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" validate:"required"`

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

	It ExtensionIT `yaml:"it"`
}

PublicCode is a publiccode.yml file definition.

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)