This folder specifies the dynamic version of SpatioTemporal Asset Catalog - the Catalog API. For now the complete definition is contained in the spec.yaml file, which is an OpenAPI 2.0 (swagger) yaml document. In time more narrative will be added describing the decisions and recommendations on implementing the STAC API.
The easiest way to explore the specification in a more human readable way is to load the file up in to the online swagger editor. You can import the spec by just selectiong 'file' -> 'import url' and enter https://raw.githubusercontent.com/radiantearth/stac-spec/dev/api-spec/spec.yaml.
This will display the documentation and examples for the specification. You can also generate code for clients and servers in a variety of languages from the editor as well, so you can get a sense of how it will work.
You can also use the yaml spec for code generation in a variety of tools.
Once OpenAPI 3.0 has more tooling support this spec will be migrated to that version of OpenAPI.