diff --git a/README.md b/README.md index 72c7733..b072c25 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ This repository contains the specification for the FAIR protocol, as well as doc * [Documentation](./docs/README.md) * [Specification](./specification.md) * [Extension Registry](./registry.md) + * [TYPO3 Extension](./ext-typo3.md) * [WordPress Extension](./ext-wp.md) This repository is managed by the FAIR Working Group. See [the TSC repo for contributing docs](https://github.com/fairpm/tsc). diff --git a/ext-typo3.md b/ext-typo3.md new file mode 100644 index 0000000..03bcb0c --- /dev/null +++ b/ext-typo3.md @@ -0,0 +1,177 @@ +# FAIR for TYPO3 Packages + +FAIR for TYPO3 Packages is an extension to the [FAIR Core specification](./specification) for the TYPO3 Content Management System (CMS). + +| Document Status: | Draft | +| ---------------- | ----- | + +## Package Types + +This specification provides the following package types and associated semantic meanings: + +| Type | Description | +| ----------------- | ------------------------------------------------------------ | +| `typo3-core` | Reserved for future use | +| `typo3-extension` | Extensions for the TYPO3 CMS | +| `typo3-theme` | Reserved for future use | + + +## Core + +*to be specified* + + +## Common + +For the `typo3-extension` and `typo3-theme` package types, several definitions are common. + +```json +keywords: [], +compatibility: [], +typo3: { + extension-key: "key-name" +} +``` + +### Metadata Document + +#### sections + +All common section types specified in FAIR Core and in this specification MAY use HTML formatting. Clients SHOULD perform sanitization on section content to ensure only safe HTML is rendered. + + +### Release Document + +The following are extensions to the Release Document specified in FAIR Core. + +#### requires and suggests + +The `requires` and `suggests` properties (collectively, dependencies) MAY contain further values specified here. + +Dependencies MAY require a certain version of the PHP software, specified as `env:php`. + +Dependencies MAY require PHP extensions, specified with a `env:php-` prefix. + +Dependencies MAY require the TYPO3 CMS, specified as `env:typo3`. + + +## Core Package Type + +The `typo3-core` package type indicates packages containing the TYPO3 CMS, or alternative distributions of it. + + +### Release Document + +The following are extensions to the Release Document specified in FAIR Core. + +#### artifacts + +The following artifact types are defined for the `typo3-core` type. + +##### package + +The common `package` type is used for the artifact containing the installable PHP application. + +This artifact SHOULD be a zip or tarball archive containing a single directory. Clients SHOULD treat the single directory within the archive as representing the installable PHP application, and MUST NOT rely on this directory having a fixed name. + +Repositories SHOULD publish at least one `package` artifact using the `application/zip` MIME type. + + +## Plugin Package Type + +The `typo3-extension` package type indicates plugins compatible with the TYPO3 CMS. + + +### Metadata Document + +The following are extensions to the Metadata Document specified in FAIR Core. + + +#### sections + +The following keys are specified in addition to the common sections. + +The following keys and their semantic meaning are specified: + +* `installation` - Instructions to the user on how to install the package. +* `faq` - Frequently asked questions about the package. +* `other_notes` - Miscellaneous additional notes. +* `screenshots` - Preview images of the package's UI. + +Additionally, the following are recognised as aliases: + +* `change_log` - Alias for `changelog`. +* `frequently_asked_questions` - Alias for `faq`. +* `screenshot` - Alias for `screenshots`. + +All section content MAY contain HTML + + +### Release Document + +#### artifacts + +The following artifact types are defined for the `typo3-extension` type. + + +##### package + +The common `package` type is used for the artifact containing the installable PHP plugin. + +Repositories SHOULD publish at least one `package` artifact using the `application/zip` MIME type. Clients may fail to install packages without a zip archive artifact. + + +##### icon + +The `icon` artifact type is used for an icon representing the package. + +Icons SHOULD be a square image, with dimensions 128x128 or 256x256. The `height` and `width` properties SHOULD be specified as numbers for raster images, indicating the dimensions of the image. + +Icons SHOULD specify the `content-type` property, with an image MIME type matching `image/png`, `image/jpeg`, `image/svg`, or `image/gif` types. Clients MAY ignore unknown types or non-image types. + +Icons MAY specify a `lang` property, which is a string containing an [RFC4646][]-compliant ("IETF") language specifier. Clients MAY conditionally show icons based on the user's language. + +Icons SHOULD NOT require authentication. + +[rfc4646]: https://datatracker.ietf.org/doc/html/rfc4646 + + +##### banner + +The `banner` artifact type is used for header banners to display on plugin listing pages. + +Banners SHOULD specify the `height` and `width` properties as numbers for raster images, indicating the dimensions of the image. Banners SHOULD NOT exceed 4MB. + +The sizes 772x250 and 1544x500 are commonly used by clients. Clients MAY ignore banners which do not match a usable size. + +Banners SHOULD specify the `content-type` property, with an image MIME type matching `image/png`, `image/jpeg`, `image/svg`, or `image/gif` types. Clients MAY ignore unknown types or non-image types. + +Banners MAY specify a `lang` property, which is a string containing an [RFC4646][]-compliant ("IETF") language specifier. Clients MAY conditionally show icons based on the user's language. + +Banners SHOULD NOT require authentication. + + +##### screenshot + +The `screenshot` artifact type is used for screenshots of the plugin's UI. + +Screenshots SHOULD specify the `height` and `width` properties as numbers for raster images, indicating the dimensions of the image. Linked artifacts SHOULD NOT exceed 10MB. + +Screenshots SHOULD specify the `content-type` property, with an image MIME type matching `image/png`, `image/jpeg`, `image/svg`, or `image/gif` types. Clients MAY ignore unknown types or non-image types. + +Screenshots MAY specify a `lang` property, which is a string containing an [RFC4646][]-compliant ("IETF") language specifier. Clients MAY conditionally show icons based on the user's language. + +Screenshots SHOULD NOT require authentication. + + + +#### requires + +The `requires` property SHOULD only contain valid package IDs for other `typo3-extension`-type packages, or PHP environment requirements as specified in [Common](#common). + +Clients MAY treat the package as invalid if other package types are required. + + +## Theme Package Type + +*to be specified* diff --git a/registry.md b/registry.md index 1d507dc..ee75b7d 100644 --- a/registry.md +++ b/registry.md @@ -8,16 +8,19 @@ This document is a registry for the known extensions to the FAIR Package Managem | -------------------------------------------- | ------------------ | | [FAIR Authentication Methods](./ext-auth.md) | FAIR Working Group | | [FAIR for WordPress Packages](./ext-wp.md) | FAIR Working Group | +| [FAIR for TYPO3 Packages](./ext-typo3.md) | FAIR Working Group | ## Package Types -| Type | Extension | Contact | -| ----------- | ------------------------------------------ | ------------------ | -| `wp-core` | [FAIR for WordPress Packages](./ext-wp.md) | FAIR Working Group | -| `wp-plugin` | [FAIR for WordPress Packages](./ext-wp.md) | FAIR Working Group | -| `wp-theme` | [FAIR for WordPress Packages](./ext-wp.md) | FAIR Working Group | - +| Type | Extension | Contact | +| ----------------- | ------------------------------------------ | ------------------ | +| `wp-core` | [FAIR for WordPress Packages](./ext-wp.md) | FAIR Working Group | +| `wp-plugin` | [FAIR for WordPress Packages](./ext-wp.md) | FAIR Working Group | +| `wp-theme` | [FAIR for WordPress Packages](./ext-wp.md) | FAIR Working Group | +| `typo3-core` | Reserved for future use. | FAIR Working Group | +| `typo3-extension` | [FAIR for TYPO3 Packages](./ext-typo3.md) | FAIR Working Group | +| `typo3-theme` | Reserved for future use. | FAIR Working Group | ## Authentication Methods