FileMeta

File Identity and Metadata Project
by Brandt Redd

CodeBit

A CodeBit is an application of FileMeta Principles to accomplish lightweight code sharing. The unit of sharing is a single source code file called a CodeBit. Each CodeBit file begins with metadata encapsulated in a comment so that it doesn’t interfere with the function of the code itself. The metadata follows the SoftwareSourceCode schema from Schema.org and is encoded in MetaTag format.

The metadata includes a keyword indicating that the file is a CodeBit, the name, a URL to the latest version, and a version number. Optional fields include description, copyright, license, and so forth.

This page includes the following sections:

Also see the Blog for history and new developments.

Coming soon will be a specification for simple CodeBit repositories, a console application for downloading and validating CodeBits, and my own repository of CodeBits.

CodeBit Specification

Metadata for this specification in MetaTag format

&name=”CodeBit Specification”
&version=2.1
&author=”Brandt Redd”
&datePublished=2022-11-09
&license=https://creativecommons.org/licenses/by/4.0/
&description=”A specification for reusable source code that is programming language independent.”
&url=http://www.filemeta.org/CodeBit

In the following text, ALL CAPS key words should be interpreted per RFC 2119.

CodeBits are source code files with a metadata block near the beginning of the file. The metadata are in MetaTag format and uses metadata property definitions from the SoftwareSourceCode type of Schema.org. At a minimum, the metadata block MUST include the name, url, version, and keywords properties and “CodeBit” MUST appear in the keywords. RECOMMENDED properties include datePublished, author, description, and license. Other metadata properties are optional and should be selected from Schema.org.

The metadata block SHOULD be enclosed by multiline comment delimiters appropriate to the programming language. Single-line comment delimiters MAY be used.

Sample Metadata Block

Here is a sample metadata block for a C# source code file.

/*
&name=example.com/MySharedCode.cs
&description="Shared code demonstration module"
&url=https://github.com/FileMeta/AcmeIndustries/raw/main/MySharedCode.cs
&version=1.4.0
&keywords=CodeBit
&datePublished=2017-05-24
&author="Adam Smith"
&copyrightHolder="ACME Industries"
&copyrightYear=2017
&license=https://opensource.org/licenses/BSD-3-Clause
*/

Properties

Properties follow the definitions in schema.org. These are specific details on how they are interpreted for codebits.

name

The name SHOULD be the registered domain name of the publisher followed by a slash, followed by the preferred filename of the codebit. The filename SHOULD include the extension associated withthe programming language (e.g. “example.com/peacemaker.js”). Additional slashes MAY separate components of the name (e.g. “example.com/category/dwim.js”) There SHOULD be no spaces in the name and there SHOULD NOT be consecutive slashes.

url

The url property SHOULD be the URL of the most recent release of the CodeBit. That is, if a CodeBit is updated, the new version is placed at same URL where the prior version was located. Older versions may exist at other URLs. See the Versioning section for details.

version

The version value SHOULD use semantic versioning. Per that standard, the simplest form includes three numbers separated by periods.

keywords

A codebit is distinguished from other source code files by the presence of the CodeBit keyword. Per the MetaTag specification a multi-valued property like keywords includes a separate tag for each keyword. So, if the keywords “CodeBit” and “Collection” are both to be included, the code would be &keywords=CodeBit &keywords=Collection.

datePublished

All dates, including datePublished MUST use RFC 3339 format which is a profile of ISO 8601. datePublished SHOULD be just a date. For example, “1986-12-25”.

A Note on Versioning

The url attribute of a CodeBit SHOULD reference the most recent release, even if the CodeBit in which the metadata is located is not the most recent.

When included, datePublished SHOULD be the date that this version was released for use.

CodeBits are incorporated into other software applications by value, not by reference. That is, the whole CodeBit file is included with an application’s other source files and stored in the application’s code repository. Thus, if a CodeBit is updated, it takes deliberate action by users of a CodeBit to update their software to a more recent release.

While CodeBits include a version number, this specification does not (yet) indicate a way to discover older versions. A potential future enhancement would be a updateTo property similar to the Schema.org successorOf property. This would allow CodeBit tools to trace a version chain to retrieve a specific release. Another option would be to use the APIs of a source code repository like GitHub to discover versions from prior commits.

For the present, it remains a manual process to locate earlier versions of a CodeBit. This is not a serious issue. The critical version of a CodeBit is the version that is used on the current build of a consuming application. That should be included with the application’s source code. Next most critical is the latest version and that is available at the url specified in the metadata.

Known CodeBits

The following is a short (but growing) list of known CodeBits. Some of these still use the CodeBit 1.0, YAML format for metadata but they will be updated before the end of 2022

  • ConsoleHelper: (C#) A class for making .Net Framework console applications more friendly when invoked from a debugger or a shortcut.
  • DateTag: (C#) A class that represents date/time metadata including timezone and precision information often neglected by other date parsers and formatters.
  • ExifToolWrapper: (C#) A wrapper class for Phil Harvey’s excellent ExifTool.
  • HtmlReader: (C#) A compact and full-featured HTML parser for .NET that implements the XmlReader interface.
  • IsomCoreMetadata (C#) A class for retrieving and updating core metadata from files in .MP4, .MOV, .M4A, and other ISO Based Media Format files.
  • MetaTag A class for embedding and extracting metadata tags in free-form text fields according to the proposed MetaTag specification.
  • MicroYaml: (C#) A simple parser and serializer for the MicroYaml dialect of the YAML file format.
  • TimeZoneTag: (C#) A class for parsing and formatting TimeZone metadata.
  • WinShellPropertyStore: (C#) .NET Wrapper classes for the Windows Property System.