publiccode

package module
v3.1.3 Latest Latest
Warning

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

 Go to latest Published: Jun 3, 2024 License: EUPL-1.2 Imports: 28 Imported by: 3

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)

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

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

View Source 
const Version = "0.3"

Version of the latest PublicCode specs.

Variables

View Source 
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.

View Source 
var ExtensionITVersion = "0.2"

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

View Source 
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.

Functions

This section is empty.

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

	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)

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.