WARNING: This document is now maintained at https://github.com/rwxrob/ocms/spec as of Sunday, October 2, 2022, 10:18:29AM EDT. Eventually, that will be a copy of whatever is at https://ocms.cc when that is up.
This is the specification for Open Credential Merit System credentials, informally referred to as “badges”. OCMS (“Occam’s”) badges are central to OCMS itself. (See https://ocms.cc for more.)
💬 Use the term “credential” when listing badges earned on resumes and other formal education and training sections. Use the term “badge” to save time when discussing credentials informally.
Each badge is composed of meta data and layered requirements separated
into distinct YAML documents within a single file separated by the
standard YAML document separator (---) for all but the first (meta
data) section.
However, unlike YAML the meta data first section must not contain any
blank or commented lines and must not begin with the YAML separator and
the first line must be the ocms meta data property (ex: ocms: v1.
This allows applications to quickly determine the state of the
credential specification without necessarily downloading the entire file
which allows OCMS registries and discovery tools to automate updates
regularly.
The first YAML document within the file (.[0]) contains the following
meta data:
💬 Meta data identifiers will never exceed seven Unicode word characters allowing them to be always easily readable on one line from any terminal.
💡 Use
yq e file.yaml | jq -s '.[0]'to access, for example, only the meta data YAML document withinfile.yaml.
ocms (required) identifies the version of the OCMS credential data
schema. It must always be the first line in the file and will almost
always be exactly the same. This allows potential changes to the
organization of the YAML file itself to change over time without
impacting applications that have been built expecting a specific format.
name (required) is a simple, succinct name (no more than 30 Unicode
word characters) in the specified language that conveys the core topic
of the credential/badge. This may include multiple words, but single
word names (including acronyms) are strongly encouraged (ex: Linux,
Sculpture, 3D Modeling, YAML). The name should combine well with the
single word names for the levels (ex: “UNIX Basics”, “UNIX Essentials”,
etc.)
url (required) is the universal resource locator which must be
a unique web address pointing to base directory containing the YAML
files (ex: ocms.rwx.gg/unix). The URL may contain any valid URL
characters including sub-directories (though discouraged since these
will be used as prereqs) but the final directory must exactly match
the base name of the main English OCMS credential specification file (ex:
ocms.rwx.gg/unix/unix.yaml) and contain only ASCII lowercase letters,
numbers, or underscore ([a-z0-9_]). The URL must be accessible
publicly with simple tools like curl and the schema portion of the URL
must be omitted (and is assumed to be https or http).
⚠️ It is vitally important that the
urlof a badge never change. Put great thought into it including who will inherit the domain name beyond the lifetime of the original author. For all intents and purposes, any change to theurlconstitutes creation of a new badge specification. Though not as succinct, often the use of a hosting service domain such asgithub.iomay be preferable due to its permanence.
issues (optional) provides the URL home where issues including errors
and suggestions may be submitted by the public. This should be more than
just a web site and will usually be the web address of a source hosting provider, but not always. The https or http schema portion may be omitted and will be assumed.
version (required) is the semantic version of the credential itself.
Only major versions should be trusted by those wanting to follow them.
Minor version changes should only be for adding new optional
requirements (never for removing or changing base requirements). This
fulfills the “non-breaking changes” idea of semantic versioning. The
patch version changes will be very frequent since they relate to the
simpler things like grammar and spelling fixes and such without changing
things like identifier names and other things in the minor version
scope. For convenience, any previous version of an OCMS credential
specification file may be included along with the current one provided
the version is added in the file name immediately after the base name
and preceding any language portion separated by a single dash (ex:
unix-v1.2.34-fr.yaml). The most recent version, however, must never
include the version in the file name.
lang (required) is the HTML ISO language code known best for its use
in the <html> tag. For consistency, all OCMS credentials should first
be written and maintained in English. This prevents misunderstandings
due to translation. All supported languages must be maintained at the
same location in order to preserve the same URL, but all languages
other than English must each have their own file with the lang coded
added with a dash to the base portion of the file name (ex: unix.yaml
and unix-fr.yaml).
levels (required) is an array/list of names for each level
corresponding to the following YAML sections of the file. Each name must
not exceed twelve Unicode word characters and may not include any
punctuation or whitespace. Level names will be added to the base name
to quantify rhetorical references to specific credential levels (ex:
UNIX Basics). All credentials are required to have at least one level.
There is no specified maximum number of levels. Badge creators may
decide how they wish to define the distinction between badge levels.
However, it is strongly recommended to limit the number of levels to
five using the following scale, scope, and names for consistency and
reduced complexity:
For convenience, the name “Proficiency” can be dropped since that is the default assumed level. The other levels are either remedial or exceptional to base, professional proficiency.
💬 Limiting scope and depth is a challenge facing all learners (as well instructional designers). “How much should I learn?” Creating levels answers this question with another: “How much do you need to learn?”
This distinction of levels also best accommodates the need for inter-dependencies. One credential might require that only level one be completed before attempting it. Another might require a full (level three) proficiency instead. This clarity makes navigating an otherwise complex set of learning requirements relatively easy, even fun since it adds an element of gamification to the learning process.
Each level is composed of a non-rooted tree of requirements; there may be more than one top-level requirement and every requirement (at any depth) may have one or more sub-requirements.
prereqs:
- [ ocms.rwx.gg/computers, 3 ]
philosophy:
onebest:
integration:
filters:
textual:
scripting:
posix:
variables:
types:
numbers:
conditions:
The optional, reserved prereqs requirement (which is first by
convention, if included) contains an array/list of other OCMS
credentials by their url and level. These credentials must be earned
before attempting the credential level containing the prereqs. Upper
levels of a single badge assume a prereqs entry for all the previous
levels for that same badge. They do not need to be listed.
All other requirement entries use their own identifiers. Each
requirement identifier must contain only lowercase ASCII alpha
characters and the underscore ([a-z_]). Numbers are not allowed.
Requirement identifiers beginning with underscore indicate that the
requirement is to be temporarily ignored either because it is being
prepared or recently deprecated. Temporary identifiers should be
removed completely within a reasonable amount of time. Simple,
single-word identifiers are preferred for their mnemonic value. A single
underscore may be used to separate one or more words in the identifier,
but multiple words should be avoided whenever possible.
⚠️ Remember, potentially millions of learners will be referring to badges and requirements by their identifiers so picking good, mnemonic ones is a critical priority — especially given their permanence. Be careful to pick identifiers that are full English words.
Each requirement has the following reserved key/value pairs:
line (required) contains a single line of no more than 50 Unicode word
characters in plain text (no emojis allowed) describing the requirement
as it would be listed as a bullet point in a resume, job description, or
presentation. It must begin with a capitalized verb, use sentence case,
and not end with any punctuation at all.
text (optional) contains a single paragraph of no more than 500
Unicode word characters of CommonMark markdown text describing the
requirement. This text is primarily intended to help remind the learner
and mentor what the requirement is about. Additional explanatory text
should be maintained outside of the OCMS credential specification itself
in a site, PDF, or pamphlet.
⚠️ Consider carefully what is added to the requirement. Any change, even a minor change in grammar or spelling correction must always trigger a version change. When in doubt leave text out and maintain such explanatory documents outside of the credential specification.
time (required) is the estimated number of hours the average learner
would require to complete this specific requirement. Decimal numbers are
allowed (ex: 0.5 is half an hour).
weight (required) is the how important this specific requirement is to
the overall learning.
💬 The Beginner Boost Badges are OCMS Credentials grouped and associated with the rwxrob.tv Beginner Boost series of videos.
Related:
Tags:
#ocms #edtech #spec #todo