As suggested by @bast.

Cf. force11/force11-sciwg#24 (comment), CFF should be expressable in CSL.

Specify how the language should be informed.

As an affiliation will always be a named entity, future versions could have the key accept an entity object rather than a string.

Because you should always start off by eating your own dog food.

Change instances of "work" to "reference", as this is the term that most users will most likely be used to in the context of citations.

Clients (human and software alike) should be able to identify the version of CFF that is used in a CITATION.cff file.

The simplest solution would be to introduce a mandatory key cff-version.

Other options should be investigated, such as custom YAML tags, etc.

1.0-RC2 should be reviewed again and tested against CodeMeta crosswalk before releasing 1.0.

The key term is defined in the Reference Types - notable reference types section of the specification, but it's not in the reference types table, or the schema.

Is this an omission from the table/schema or a spuriously defined key?

(Happy to fix this either way once we've decided.)

This hack is about providing a complete schema for CFF-Core in PyKwalify for validation of CFF files.

The schema will be non-restrictive, so will not have to limit the reference keys that can be used in specific reference types, cf. discussion in #14.

Work should be done in https://github.com/citation-file-format/schema.

Please see the guidelines to contributing.

Bibtex should be automatically generated from the citation file.

If the CrossCite converters (@crosscite) supported CFF for DOI content negotiation, it would greatly help adoption and tooling!

1.0.0 and 1.0.1 still include examples that follow 1.0-RC1 and hence will not validate against the schema.
To be fixed in 1.0.2.

I think that dependencies need more work.

See force11/force11-sciwg#24: If it can be done, it would perhaps make sense to develop an extension "CFF Transitive" for implementing transitive credit.

In the file structure we recommend "exactly one message containing instructions ...".
This is perhaps nit-picking (but it is good to settle this early) but I was a bit surprised by the hyphen which signals that this is a list item. Why not message: If you use this software, please cite the works below. instead of the one with hyphen?

Related to this (we can split this up into a separate issue) it could be an idea to collect references to references. I.e., instead of:

- message: If you use this software, please cite the works below.
- type: software-code
  authors:
    - name: ...
      orcid: ...
- type: ...
  authors:
    - name: ...
      orcid: ...

rather:

message: If you use this software, please cite the works below.
references:
  - type: software-code
    authors:
      - name: ...
        orcid: ...
  - type: ...
    authors:
      - name: ...
        orcid: ...

The latter signals to me more clearly that there is only one message and that the types are actually references.

https://spdx.org/licenses/

A CFF conversion service should support https://wiki.debian.org/UpstreamMetadata, as mentioned in force11/force11-sciwg#45. To discuss with @mr-c.

1.0-RC1 has introduced splittable names according to W3C suggestions and the BibTeX standard of using four units (family names, given names, name particle and name suffix, cf. #10 (comment)).

This will be broken in 1.0 to achieve cross-walkability with CodeMeta, which only defines given name and family name (cf. there and @mfenner for details).

In order to re-introduce this in CFF-Core, it will have to be fixed in CodeMeta first, which depends on it being fixed in schema.org.

Integrate with https://github.com/duecredit/duecredit/

CFF should ideally be one of the formats that duecredit supports, i.e., a format that can be read into duecredit, similar to BibTeX.

See force11/force11-sciwg#24: If the purpose of CFF is to provide citation metadata, some of the unrelated keys (e.g., role in person objects, programming-languages) are unnecessary. Hence, CFF "Core" should be about citation metada only.

If feasible (#22), keys going beyond "core" could be developed further towards, e.g., an implementation of transitive credit, but this should be done in an extension (and a separate repo), e.g., "CFF Transitive".

In order to support automatic conversions, etc.: https://github.com/codemeta/codemeta

Only references items of type software (or sub-types) can be cross-walked with CodeMeta.

Stupid question: Where is the documentation on how it looks like, and maybe some examples?

I came to this site:
https://citation-file-format.github.io/
Which motivates me to use it - but does not feature examples as far as I could tell.

Then I went to github:
https://github.com/citation-file-format
It seems to have been the only link that might contain the documentation.

That contains among some language specific things (which I am currently not interested in, as I am still trying to rather understand what it is) and the websites only to repositories:

• https://github.com/citation-file-format/schema
  Which only contains (?) tests to make sure a file is valid CFF (again, don't want that yet)

• https://github.com/citation-file-format/citation-file-format
  Which contains one example file (:tada:) but in an old version and only one (rather simple) entry.

What have I missed? Where can I learn what a file looks like, except for reading the python parser in schema?

When working on #11, I discovered that Pykwalify doesn't support a list of pre-defined schemas, see https://sourceforge.net/p/kwalify/feature-requests/10/, which make impossible to have some attributes limited to some Work Types, for example commit clear make sense for software and can make sense for manual (the manual of a software) but I it doesn't make sense for me to conference.

This should be a web service for validating CFF files against the tolerant schema (#30).

Cf. https://support.orcid.org/knowledgebase/articles/116780-structure-of-the-orcid-identifier, section ""Expressing the ORCID":

The ORCID iD is expressed as an https URI, i.e. the 16-digit identifier is preceded by "https://orcid.org/". A hyphen is inserted every 4 digits of the identifier to aid readability.

This would be experimental, and produced to find out which keys are supported by schema.org and which aren't.

Should be Date for consistency.

This depends on #21.

As CodeMeta JSON emerges as the go-to format for extraction and provision of software metadata, it is imperative that CFF can interface with CodeMeta JSON.

Hence, the first converter that should be built is one for CodeMeta JSON.

It'd be great if Zotero supported CFF in that you could harvest the CFF metadata from a repository website (GitHub, GitLab, Bitbucket, etc.) via the "Save to Zotero" browser add-on (https://github.com/zotero/zotero-connectors/)!

In the status list for a publication, are we missing a "published", "complete" or "finished" status?

Stumbled over this when re-reading the principles paper: All three use cases (1, 3, 15) require Location/repository as well as Unique identifier.

However, the text mentions in sections "Access to software" and "Unique identification", that in cases where no unique identifier exist, a combination of repo URL and, e.g., commit hash or version number may be used. Therefore, the 'doi' key cannot be made required as this would lock out users providing metadata for a software without a unique ID.

Likewise, ("Access to software"):

For commercial software, the metadata should still provide information on how to access the specific software, but this may be a company’s product number or a link to a website that allows the software be purchased. As stated in the Persistence principle (4), we recognize that the software version may no longer be available, but it still should be cited along with information about how it was accessed.

Hence, repository information cannot be made required.

This information is indirectly given in Software citation metadata (required), but should perhaps be made more public in a FAQ or similar.

Create a conversion service and web frontend for converting CFF files into other formats.

Obviously, CodeMeta JSON shold be the first format to be supported.

As discussed in #9 (and more specifically https://github.com/sdruskat/citation-file-format/issues/9#issuecomment-333075185), each CFF file should have a single, global field message which has scope over the software that the CFF file is maintained for.

Every discrete "piece of software" should have its own CFF file.

This means that a larger software project may have more than one CFF file. Ideally, these would be distributed over, e.g., different nesting levels in the repository, i.e., different "directories". For example, the repo root would contain a CFF file with references to the software project as a whole, and perhaps another publication discussing the software project as a whole. Other levels may contain CFF files with references to smaller parts of the software. For example, if a Java class implements a specific algorithm which should be made available for citation via CFF, the repo level for the package containing that class should contain the CFF file giving a reference to the algorithm paper:

• Class implementing the algorithm: org.acme.bar.foo.magic.Algorithm.java
• Java package is therefore: org.acme.bar.foo.magic
• Reflected in the repo structure, e.g.: https://github.com/user/project/blob/master/src/main/java/org/acme/bar/foo/magic/`. This "directory" should contain the CFF file providing a reference to the algorithm paper.

In other cases this might not be feasible, e.g.:

• CFF files for executables bundling different packages
• Several classes implementing different algorithms in the same package
• Repo structure does not reflect package structure in a programming language

Here, I can see two options to solve this in the CFF file.

1. Use the global message to instruct the user which reference to cite for which, package/class, etc.
2. Specify a scope for each single reference which states which package/class/LOCs, etc., the reference "is meant for".

I think both options are valid.

Option 2 could either be implemented by using the notes field, but this would break Separation of Concerns, as notes will likely be used for more general purposes by creators of CFF files. Hence, I'd introduce a new key scope on the level of references whose value would be the information which software the reference(s) "are meant for".

This should be the first of hopefully a large number of CFF readers in different programming languages.

https://citation-file-format.github.io should give a good overview on its home page, including one or more simple examples to get started (cf. #50).

The home page should also list tools available, or point to a centrally maintained list in citation-file-format/citation-file-format's README.md (which should also be updated to be more accessible and informative.

I suggest to wrap the currently long lines in the source text (gq in vim). This will create more manageable diffs for small edits in text.

It makes sense (especially in the light of #23) to split up the current state of CFF across several repos:

• cff-core for the schema for a minimal format for citation metadata
• cff-transitive (if feasible) for an extension for transitive credit
• A repo for the website & docs (i.e., what's in here at the moment, Jekyll site + PDF)

A strict schema with attribute constraints for specific reference types (subschemas, e.g., disallow commit for type conference) would be a great asset.

However, this is currently not supported by the Python port for Kwalify, PyKwalify (which has a larger feature set than Kwalify), which I have originally identified as probably the best option for validating CITATION.cff files against a schema (other suggestions welcome!). See issue #12 for details.

At the moment, the plan for CFF is to have a relatively loose schema with PyKwalify, and update to a stricter schema in a later version, if and when this becomes possible in PyKwalify (cf. Grokzen/pykwalify#112).

In order to test usability and usefulness of CFF, a case study with a (smaller) repository/community should be run, which uses citation-relevant metadata, but not in a standardized format.

@npch has suggested ASCL.

This is not about whether person roles should be part of the core specs.

In the spirit of adopting best practices, it makes sense to align the person roles (pretty much developed on a gut level) with the OpenRIF Contribution Role Ontology, https://github.com/openrif/contribution-ontology.

This hack is about validating whether the format specifications in v1.0-RC1 is complete, as bug-free as possible, and applicable.

Please see the guidelines to contributing.

The specs should contain a sizable list of examples of complete CITATION.cff files, at least for the most common reference types.

Create a web service for the creation of CFF files from scratch.

This should include a web frontend where users can input their specs and create a file for download.

Should harvest available metadata from, e.g., ORCID and DOI providers or, indeed, integrate with providers' APIs to create a DOI in the process (needs to be investigated if, e.g., Zenodo supports this).