publiccode

package module
v5.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 29, 2025 License: EUPL-1.2 Imports: 30 Imported by: 0

README

publiccode.yml parser for Go

Get invited

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)

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")

Go Reference

From command line

The publiccode-parser binary can be used to validate a publiccode.yml from the command line.

To get the latest version use:

go install github.com/italia/publiccode-parser-go/v5/publiccode-parser@latest

Or get a precompiled package from the release page

Example:

$ publiccode-parser mypubliccode.yml
publiccode.yml:36:1: error: developmentStatus: developmentStatus must be one of the following: "concept", "development", "beta", "stable" or "obsolete"
publiccode.yml:48:3: warning: legal.authorsFile: This key is DEPRECATED and will be removed in the future. It's safe to drop it
publiccode.yml:12:5: warning: description.en.genericName: This key is DEPRECATED and will be removed in the future. It's safe to drop it

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

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

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
Click to expand

The examples assume that your publiccode.yml file is on your local machine, at /opt/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 the publiccode.yml project and its CONTRIBUTING.md guidelines.

See also

Maintainers

This software is maintained by community contributors.

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

This section is empty.

Variables

View Source 
var SupportedVersions = []string{"0", "0.2", "0.2.0", "0.2.1", "0.2.2", "0.3", "0.3.0", "0.4", "0.4.0", "0.5.0", "0.5"}

SupportedVersions lists the publiccode.yml versions this parser supports.

Functions

This section is empty.

Types

type ContactV0 

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

ContactV0 is a contact info maintaining the software.

type ContractorV0 

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

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

type DependencyV0 

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

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

type DescV0 

type DescV0 struct {
	LocalisedName    *string   `json:"localisedName,omitempty"    yaml:"localisedName,omitempty"`
	GenericName      string    `json:"genericName"                validate:"umax=35"                      yaml:"genericName"`
	ShortDescription string    `json:"shortDescription"           validate:"required,umax=150"            yaml:"shortDescription"`
	LongDescription  string    `json:"longDescription,omitempty"  validate:"required,umin=150,umax=10000" yaml:"longDescription,omitempty"`
	Documentation    *URL      `json:"documentation,omitempty"    validate:"omitnil,url_http_url"         yaml:"documentation,omitempty"`
	APIDocumentation *URL      `json:"apiDocumentation,omitempty" validate:"omitnil,url_http_url"         yaml:"apiDocumentation,omitempty"`
	Features         *[]string `json:"features,omitempty"         validate:"gt=0,dive"                    yaml:"features,omitempty"`
	Screenshots      []string  `json:"screenshots,omitempty"      yaml:"screenshots,omitempty"`
	Videos           []*URL    `json:"videos,omitempty"           validate:"dive,omitnil,url_http_url"    yaml:"videos,omitempty"`
	Awards           []string  `json:"awards,omitempty"           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 `json:"countryExtensionVersion" validate:"omitnil,oneof=0.2 1.0" yaml:"countryExtensionVersion"`

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

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

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

type OrganisationV0 added in v5.2.0 

type OrganisationV0 struct {
	Name *string `json:"name,omitempty" yaml:"name,omitempty"`
	URI  string  `json:"uri"            validate:"required,organisation_uri" yaml:"uri"`
}

OrganisationV0 describes a real world organisation.

type ParseError 

type ParseError struct {
	Reason string
}

ParseError is 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 (eg. URL existence). This
	// results in much faster parsing.
	DisableNetwork bool

	// DisableExternalChecks disables ALL the additional checks on external files
	// and resources, local or remote (eg. existence, images actually being images, etc.).
	//
	// It implies DisableNetwork = true.
	DisableExternalChecks 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 `` /* 135-byte string literal not displayed */

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

	IsBasedOn       UrlOrUrlArray `json:"isBasedOn,omitempty"       validate:"omitempty,dive,url_url" yaml:"isBasedOn,omitempty"`
	SoftwareVersion string        `json:"softwareVersion,omitempty" yaml:"softwareVersion,omitempty"`
	ReleaseDate     *string       `json:"releaseDate"               validate:"omitnil,date"           yaml:"releaseDate"`

	Organisation *OrganisationV0 `json:"organisation,omitempty" yaml:"organisation,omitempty"`

	InputTypes  *[]string `json:"inputTypes,omitempty"  validate:"omitempty,dive,is_mime_type" yaml:"inputTypes,omitempty"`
	OutputTypes *[]string `json:"outputTypes,omitempty" validate:"omitempty,dive,is_mime_type" yaml:"outputTypes,omitempty"`

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

	Categories *[]string `json:"categories,omitempty" validate:"omitempty,dive,is_category_v0" yaml:"categories,omitempty"`

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

	FundedBy *[]OrganisationV0 `json:"fundedBy,omitempty" validate:"omitempty,dive" yaml:"fundedBy,omitempty"`

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

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

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

	IntendedAudience *struct {
		Scope                *[]string `json:"scope,omitempty"                validate:"omitempty,dive,is_scope_v0"                     yaml:"scope,omitempty"`
		Countries            *[]string `json:"countries,omitempty"            validate:"omitempty,dive,iso3166_1_alpha2_lower_or_upper" yaml:"countries,omitempty"`
		UnsupportedCountries *[]string `` /* 133-byte string literal not displayed */
	} `json:"intendedAudience,omitempty" yaml:"intendedAudience,omitempty"`

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

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

	Maintenance struct {
		Type        string          `json:"type"                  validate:"required,oneof=internal contract community none"                        yaml:"type"`
		Contractors *[]ContractorV0 `` /* 139-byte string literal not displayed */
		Contacts    *[]ContactV0    `` /* 136-byte string literal not displayed */
	} `yaml:"maintenance" json:"maintenance"`

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

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

	IT *ITSectionV0 `json:"IT,omitempty" yaml:"IT,omitempty"`

	// Don't use, this is provided for backwards compatibility.
	// IT always has the same data.
	It *ITSectionV0 `json:"it,omitempty" yaml:"it,omitempty"`
}

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) MarshalJSON 

func (u *URL) MarshalJSON() ([]byte, error)

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)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.