publiccode

package module
v4.1.1 Latest Latest
Warning

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

 Go to latest Published: Jun 19, 2024 License: EUPL-1.2 Imports: 28 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)

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

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

This section is empty.

Variables

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

Functions

This section is empty.

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

	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)

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.