feat: bootstrap bikeshed by kburger · Pull Request #20 · fdp-specs/fdp-specs.github.io

kburger · 2025-12-16T10:13:45Z

Added an index.bs scaffold to demonstrate the use of bikeshed. Locally this can be run using:

bikeshed spec index.bs output.html

Note that the output is not on par with the existing index.html, because bikeshed is opinionated. With some css we can probably get closer, but that is out of scope for this PR.

Up for discussion:

folder/file structure and naming convention (folder per chapter, .md file naming)
bikeshed metadata (which keys to use, what values to pick)
look-and-feel
github action automation (see https://speced.github.io/bikeshed/#gh-action-ci)

todo:

replace old stuff by new stuff (done in Replace old spec files by bikeshed output #24):
- remove deprecated files and folders:
  - spec.md
  - style/
  - scripts/
  - _notes/ (dreamweaver stuff)
- move old spec versions into separate folder and update links accordingly:
  - fdp-specs-v1.0.html
  - fdp-specs-v1.1.html
  - fdp-specs-v1.2.html
flat layout for src/ (see comment) (done in Flatten the directory structure for src/ #25)

fixes #19 (?)

kburger · 2026-01-14T13:22:34Z

I'm converting the remaining chapters in this PR to keeps things together.

kburger · 2026-01-14T14:46:55Z

@luizbonino and @dennisvang, i'm looking for feedback on setup, naming, and what we're missing out on look and feel.

dennisvang · 2026-01-15T14:33:01Z

Hi @kburger, looks good already. :)

Not done reviewing, but some notes for now:

I've added some project dependencies for local dev in Specify project dependencies #21. Just a suggestion.
One thing I've noticed in the bikeshed output is that a "Conformance" section is generated, near the bottom.
In the new spec we should probably move the info from the "Compliance" section into that "Conformance" section, and move it to the top somewhere.
Would it be possible to convert the tables to markdown too, instead of html? I know this will lead to long lines of text again, but in this case I'm inclined to prefer readability of the raw markdown document.

* add .gitignore * add minimal pyproject.toml with bikeshed dev dependency * add uv.lock (showing a preference for using astral-sh/uv to manage python and packages)

kburger · 2026-01-19T09:29:12Z

@dennisvang bikeshed support commonmark, which does not include tables (see speced/bikeshed#2857 and speced/bikeshed#1128). When a markdown table is written once, and read many times I agree, but if a table needs frequent updates the maintenance of a markdown table can be cumbersome.

For the conformance section, I think it can be influences by configuration settings. That would be something to investigate.

dennisvang · 2026-01-19T09:55:09Z

@dennisvang bikeshed support commonmark, which does not include tables (see speced/bikeshed#2857 and speced/bikeshed#1128). [...]

Thanks for pointing that out. I was not aware that md tables are not supported.

[...] When a markdown table is written once, and read many times I agree, but if a table needs frequent updates the maintenance of a markdown table can be cumbersome.

Yes you're right.

dennisvang

@kburger (and @luizbonino) This looks good, but I've made some minor suggestions in the review comments, e.g. line breaks etc.

In addition, I've moved the html tables from the metadata.md markdown file into separate html files (already committed in 8e15ff0).

I've also compared all new content with that from the original v1.2 html file, word for word. This includes the text from the new markdown files, as well as the RDF from the new ttl files and the tables from the new html files.
(and confirmed that they are indeed identical)

Finally, I've suggested some minor changes to stay as close as possible to the original content, like adding the [RDF] reference and restoring section 1.2.

There's one important decision to be made, regarding the type of publication. See the this comment for details.

dennisvang · 2026-02-09T12:49:40Z

+<pre class=metadata>
+Title: FAIR Data Point
+Shortname: fdp
+Status: LS


@luizbonino, @kburger Should the spec be a draft W3C Community Group Report published by the W3C FDP community group?

That would be:

Suggested change

Status: LS

Org: W3C

Group: fdpcg

Status: CG-DRAFT

Level: none

ED: https://specs.fairdatapoint.org/

Also see CG-DRAFT.

UPDATE: I've created speced/bikeshed-boilerplate#193 to register the FDP Community Group as fdpcg.

Suggestion: use for now the unoficcial specification and use the CG-DRAFT when we start working on v2. Then we need to communicate it with the FDP CG.

So then it will become a W3C UD for now.

Sign in to view

+The FDP extends the DCAT model by adding the concept of a `FAIRDataPoint` as a specific type of data service that serves metadata catalogs and metadata records.
+The DCAT extensions and other FDP-specific concepts and relations are defined in the FDP ontology (using the namespace prefix `fdp-o`).
+In the FDP ontology, the FAIR Data Point is represented by a sub-class of the concept of `MetadataService`.
+Figure 4.1 only depicts the properties that are not already inherited from `Data Service` and `Resource`.


dennisvang · 2026-02-10T10:41:35Z

[...]

Up for discussion:

folder/file structure and naming convention (folder per chapter, .md file naming)

[...]

@kburger @luizbonino Personally I would prefer a (more) flat file structure as follows:

src
├── api.md
├── architecture.md
├── compliance.md
├── intro.md
├── metadata.md
├── overall.md
├── tables
│   ├── table-catalog-metadata.html
│   ├── table-fdp-metadata.html
│   └── table-navigation-information.html
└── turtles
    ├── example-metadataservice.ttl
    ├── shacl-catalog.ttl
    └── shacl-fdp.ttl

simpler
more convenient w.r.t. collapsing/expanding trees in IDEs
see what's in src/ at a glance, instead of needing to descend into nested dirs
no real need to collect chapters in separate dirs (yet)

What do you think?

Co-authored-by: Dennis <29799340+dennisvang@users.noreply.github.com>

dennisvang · 2026-02-16T12:19:52Z

+<pre class=metadata>
+Title: FAIR Data Point
+Shortname: fdp
+Status: LS


So then it will become a W3C UD for now.

Co-authored-by: Dennis <29799340+dennisvang@users.noreply.github.com>

* add github build-validate workflow, using the w3c/spec-prod action * run workflow on pull request and on push to development branch * prevent duplicate workflows

already discussed and done

* move markdown files from subdirs into src/ and update index.bs accordingly * move src/metadata/tables/ to src/tables/ and update refs * rename src/metadata/ to src/rdf/ and update refs * fix img tags

* update index.html with bikeshed build * remove duplicate image and unused images * remove deprecated style/, scripts/, images/_notes/ * remove deprecated spec.md * create standalone copies of old versions in separate directories (Basically we just create snapshots of the old versions of the spec, including all relevant resources, in separate directories. This introduces some duplication of resources (images, style, scripts), but it makes each version self-contained. A DRY approach using git history will be considered at a later stage.) * adapt all links to new file structure and make image links relative to enable simple snapshot copy

kburger mentioned this pull request Dec 16, 2025

Use the W3C bikeshed tool #19

Closed

kburger force-pushed the feature/bikeshed-scaffolding branch from 6ac6044 to ceced02 Compare December 16, 2025 12:40

feat: bootstrap bikeshed with first two chapters

ddc5b6f

kburger force-pushed the feature/bikeshed-scaffolding branch from ceced02 to ddc5b6f Compare December 16, 2025 12:41

dennisvang reviewed Dec 16, 2025

View reviewed changes

Comment thread src/introduction/intro.md Outdated

kburger added 2 commits December 22, 2025 09:14

style: separate sentences on lines

84527d9

feat: add additional chapters

f5c516c

feat: add schema tables

7e8a2b2

kburger marked this pull request as ready for review January 14, 2026 14:46

dennisvang changed the title ~~feat: bootstrap bikeshed with first two chapters~~ feat: bootstrap bikeshed Jan 15, 2026

Specify project dependencies (#21)

632effe

* add .gitignore * add minimal pyproject.toml with bikeshed dev dependency * add uv.lock (showing a preference for using astral-sh/uv to manage python and packages)

move html tables from metadata.md into separate files

8e15ff0

dennisvang previously requested changes Feb 10, 2026

View reviewed changes

dennisvang and others added 6 commits February 10, 2026 14:22

adapt table style from original v1.2 spec

d7434ba

Update index.bs

43d6428

Co-authored-by: Dennis <29799340+dennisvang@users.noreply.github.com>

Update src/compliance/compliance.md

043c669

Co-authored-by: Dennis <29799340+dennisvang@users.noreply.github.com>

Update src/metadata/metadata.md

a7d1a1e

Co-authored-by: Dennis <29799340+dennisvang@users.noreply.github.com>

Update src/introduction/intro.md

97e75c0

Co-authored-by: Dennis <29799340+dennisvang@users.noreply.github.com>

Apply suggestions from code review

272f808

Co-authored-by: Dennis <29799340+dennisvang@users.noreply.github.com>

dennisvang reviewed Feb 16, 2026

View reviewed changes

luizbonino and others added 2 commits February 16, 2026 13:30

Apply suggestions from code review

e2dc508

Co-authored-by: Dennis <29799340+dennisvang@users.noreply.github.com>

fix W3C unofficial draft configuration

7d59f5c

dennisvang mentioned this pull request Feb 16, 2026

Switch to W3C CG-DRAFT for next release #23

Open

Github workflow for bikeshed validation (#22)

430866d

* add github build-validate workflow, using the w3c/spec-prod action * run workflow on pull request and on push to development branch * prevent duplicate workflows

dennisvang mentioned this pull request Feb 16, 2026

Flatten the directory structure for src/ #25

Merged

dennisvang added 3 commits March 2, 2026 13:43

Flatten the directory structure for src/ (#25)

95917b6

* move markdown files from subdirs into src/ and update index.bs accordingly * move src/metadata/tables/ to src/tables/ and update refs * rename src/metadata/ to src/rdf/ and update refs * fix img tags

uv.lock upgrade dependencies to latest versions

4d58188

dennisvang merged commit 5e122bf into development Mar 12, 2026
1 check passed

dennisvang deleted the feature/bikeshed-scaffolding branch March 12, 2026 10:52

-Status: LS
+Org: W3C
+Group: fdpcg
+Status: CG-DRAFT
+Level: none
+ED: https://specs.fairdatapoint.org/

Conversation

kburger commented Dec 16, 2025 • edited by dennisvang Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

kburger commented Jan 14, 2026

Uh oh!

kburger commented Jan 14, 2026

Uh oh!

dennisvang commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kburger commented Jan 19, 2026

Uh oh!

dennisvang commented Jan 19, 2026

Uh oh!

dennisvang left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dennisvang Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

luizbonino Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

dennisvang Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

dennisvang commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dennisvang Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kburger commented Dec 16, 2025 •

edited by dennisvang

Loading

dennisvang commented Jan 15, 2026 •

edited

Loading

dennisvang left a comment •

edited

Loading

dennisvang commented Feb 10, 2026 •

edited

Loading