sslabdata 3.0.0__tar.gz → 3.1.0__tar.gz

{sslabdata-3.0.0/sslabdata.egg-info → sslabdata-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sslabdata
-Version: 3.0.0
+Version: 3.1.0
 Summary: Renderer-agnostic academic lab data assembler: BibTeX + YAML → structured data
 Author: Siddhartha Srinivasa
 License-Expression: MIT
@@ -91,6 +91,21 @@ pytest
 
 The `test` extra installs `pytest` and `jsonschema`, which the tests need.
 
+## Start a new lab
+
+```bash
+sslabdata init mylab
+cd mylab && sslabdata --config lab.yaml --validate --strict
+```
+
+`init` writes `lab.yaml`, `bib/publications.bib`, `people.yaml`,
+`projects.yaml` and `collaborators.yaml` into `mylab/` (the current directory
+if you name none), each with one fictional record and a comment on each
+field. Replace them with your own. It never overwrites a file that is already
+there and names each one it refuses; `--force` overwrites those files and
+nothing else. The paths in `lab.yaml` are relative to the directory you run
+sslabdata from, so run it from `mylab/`.
+
 ## Write `lab.yaml`
 
 ```yaml
@@ -107,7 +122,7 @@ bib_files:
   - name: "conference.bib"
     category: "Conference Papers"
 
-pdf_base_url: "https://mylab.example.org/pdfs"
+pdf_base_url: "https://mylab.example.org/pdfs"  # optional; leave out to guess no PDF links
 people_file: "data/people.yaml"       # optional
 projects_file: "data/projects.yaml"   # optional
 collaborators_file: "data/collaborators.yaml"  # optional
@@ -260,6 +275,30 @@ reported under `RESOLVE-COLLABORATOR-ALIAS-IS-MEMBER` and left to the member.
 person's `photo`, and is `null` when absent. It is carried as plain text:
 deciding which URLs are safe to render is the renderer's job.
 
+### Checking inputs in an editor
+
+Each input file has a JSON Schema in
+[`schema/input/v1/`](https://github.com/siddhss5/sslabdata/tree/main/schema/input/v1):
+`lab.schema.json`, `people.schema.json`, `projects.schema.json` and
+`collaborators.schema.json`. The wheel installs them under
+`sslabdata/schema/input/v1/`. An editor can use them to check and complete
+the files as you write; `--validate` stays the check, and also reports what
+a schema cannot see, such as a repeated id or a missing file. With the YAML
+language server (the VS Code YAML extension, among others), name the schema
+in a comment at the top of the file:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/siddhss5/sslabdata/input-schema-v1/schema/input/v1/people.schema.json
+- id: "aadams"
+  name: "Alice Adams"
+  role: "professor"
+```
+
+The URL is the schema's `$id`, served from the `input-schema-v1` tag, which is
+never moved ([`SPEC.md` §6](https://github.com/siddhss5/sslabdata/blob/main/SPEC.md#6-version-policy)).
+Use `lab.schema.json`, `projects.schema.json` or `collaborators.schema.json`
+in the same way for the other files.
+
 ## How author matching works
 
 sslabdata matches the structured parts of each BibTeX author name (given, von,
@@ -381,7 +420,10 @@ Trusted Publishing; no token is stored anywhere. The version is written in
 2. **Release.** Set both versions to `3.0.0`, date the CHANGELOG heading,
    merge, and push the tag `v3.0.0`. The PyPI job waits in the `release`
    environment for a reviewer's approval, then publishes the files the run
-   checked and creates the GitHub Release with them.
+   checked and creates the GitHub Release with them. A release that ships a
+   new schema version also pushes that version's tag, `schema-vN` or
+   `input-schema-vN`, at the same commit, since the schema's `$id` points
+   there.
 3. **Approve** from the Actions page, or from the command line:
 
    ```bash

{sslabdata-3.0.0 → sslabdata-3.1.0}/README.md

@@ -54,6 +54,21 @@ pytest
 
 The `test` extra installs `pytest` and `jsonschema`, which the tests need.
 
+## Start a new lab
+
+```bash
+sslabdata init mylab
+cd mylab && sslabdata --config lab.yaml --validate --strict
+```
+
+`init` writes `lab.yaml`, `bib/publications.bib`, `people.yaml`,
+`projects.yaml` and `collaborators.yaml` into `mylab/` (the current directory
+if you name none), each with one fictional record and a comment on each
+field. Replace them with your own. It never overwrites a file that is already
+there and names each one it refuses; `--force` overwrites those files and
+nothing else. The paths in `lab.yaml` are relative to the directory you run
+sslabdata from, so run it from `mylab/`.
+
 ## Write `lab.yaml`
 
 ```yaml
@@ -70,7 +85,7 @@ bib_files:
   - name: "conference.bib"
     category: "Conference Papers"
 
-pdf_base_url: "https://mylab.example.org/pdfs"
+pdf_base_url: "https://mylab.example.org/pdfs"  # optional; leave out to guess no PDF links
 people_file: "data/people.yaml"       # optional
 projects_file: "data/projects.yaml"   # optional
 collaborators_file: "data/collaborators.yaml"  # optional
@@ -223,6 +238,30 @@ reported under `RESOLVE-COLLABORATOR-ALIAS-IS-MEMBER` and left to the member.
 person's `photo`, and is `null` when absent. It is carried as plain text:
 deciding which URLs are safe to render is the renderer's job.
 
+### Checking inputs in an editor
+
+Each input file has a JSON Schema in
+[`schema/input/v1/`](https://github.com/siddhss5/sslabdata/tree/main/schema/input/v1):
+`lab.schema.json`, `people.schema.json`, `projects.schema.json` and
+`collaborators.schema.json`. The wheel installs them under
+`sslabdata/schema/input/v1/`. An editor can use them to check and complete
+the files as you write; `--validate` stays the check, and also reports what
+a schema cannot see, such as a repeated id or a missing file. With the YAML
+language server (the VS Code YAML extension, among others), name the schema
+in a comment at the top of the file:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/siddhss5/sslabdata/input-schema-v1/schema/input/v1/people.schema.json
+- id: "aadams"
+  name: "Alice Adams"
+  role: "professor"
+```
+
+The URL is the schema's `$id`, served from the `input-schema-v1` tag, which is
+never moved ([`SPEC.md` §6](https://github.com/siddhss5/sslabdata/blob/main/SPEC.md#6-version-policy)).
+Use `lab.schema.json`, `projects.schema.json` or `collaborators.schema.json`
+in the same way for the other files.
+
 ## How author matching works
 
 sslabdata matches the structured parts of each BibTeX author name (given, von,
@@ -344,7 +383,10 @@ Trusted Publishing; no token is stored anywhere. The version is written in
 2. **Release.** Set both versions to `3.0.0`, date the CHANGELOG heading,
    merge, and push the tag `v3.0.0`. The PyPI job waits in the `release`
    environment for a reviewer's approval, then publishes the files the run
-   checked and creates the GitHub Release with them.
+   checked and creates the GitHub Release with them. A release that ships a
+   new schema version also pushes that version's tag, `schema-vN` or
+   `input-schema-vN`, at the same commit, since the schema's `$id` points
+   there.
 3. **Approve** from the Actions page, or from the command line:
 
    ```bash

{sslabdata-3.0.0 → sslabdata-3.1.0}/SPEC.md

@@ -29,8 +29,8 @@ Pointer into `schema/v5/output.schema.json` such as `/$defs/person/required`, or
 a `tests/COVERAGE.md` row key such as `config.people_file.missing`. A bare
 statement is cited by its enclosing function.
 
-Nothing yet checks that these references resolve; #63 proposes the test that
-would.
+`tests/test_spec_references.py` checks that every one of these references
+resolves; its docstring says which spans count as references.
 
 ---
 
@@ -72,6 +72,35 @@ Flags, as `sslabdata.cli.main()` defines them:
 | `--unresolved` | List author names that matched no person, then exit. A name left ambiguous is one of them. |
 | `--strict` | Combines with any mode. Every coded diagnostic is an error except those the class table below marks as never an error: a redefined `@string` macro, and anything about an author who matched no lab member. Any error exits `1`, and an export writes nothing. Without it, the exit codes below are unchanged. |
 
+**`sslabdata init [DIR] [--force]`** is the one subcommand, recognised only as
+the first argument (`sslabdata.cli.main()`). The flag form takes no positional
+argument, so no command line that form accepts begins with `init`, and every
+such command line behaves as it did before `init` existed. `init` writes a
+minimal starting point that passes `--validate --strict` into `DIR` (default:
+the current directory), creating it if it is missing: `lab.yaml`,
+`bib/publications.bib`, `people.yaml`, `projects.yaml` and
+`collaborators.yaml`, each holding one fictional record and copied unchanged
+from the package's data (`sslabdata.cli.INIT_FILES`). Nothing is fetched.
+The paths in the `lab.yaml` it writes are relative to `DIR`, so the next
+command, which it prints last on standard output after a `Wrote <path>` line
+per file, runs from there. Every problem is found before any file is
+written, so a refused run writes nothing:
+
+- a file already at one of those paths is never overwritten without
+  `--force`, and each one is named (`INIT-FILE-EXISTS`); `--force`
+  overwrites those files and touches nothing else, replacing each
+  atomically, so a failed write leaves the old file as it was. A symlink is
+  replaced itself, never what it points to;
+- `DIR` or `DIR/bib` that is not a directory, or a path it writes that is a
+  directory or is not a regular file, is refused even with `--force`
+  (`INIT-PATH-WRONG-KIND`);
+- a `DIR/bib` that resolves outside `DIR` through a symlink is refused
+  (`INIT-PATH-OUTSIDE-DIR`).
+
+A failure to create `DIR` or write a file is `INIT-WRITE-FAILED`. Every
+`INIT-` diagnostic is unprefixed on standard error and exits `1`; a usage
+error exits `2`.
+
 **At least one** of `--output`, `--validate` or `--unresolved` is required —
 not exactly one. `sslabdata.cli.main()` rejects only the case where all three
 are absent, so combinations are accepted and resolved by **precedence**:
@@ -84,9 +113,9 @@ Exit codes, as `sslabdata.cli.main()` returns them:
 
 | Code | Meaning |
 |---|---|
-| `0` | Success. `--output` wrote the file; `--validate` found no errors; `--unresolved` reported. |
-| `1` | Error. Configuration file missing, or configuration failed to load — unreadable, a `bib_files[].name` that is absolute or leaves `bib_dir`, a `lab.yaml` of the wrong shape, or a value under `lab` that has no one JSON form; a path the configuration names is not there, or is not a file (not a directory, for `bib_dir`); a people file cannot be read as records; an entry carries `crossref`; `--validate` found unknown project ids or duplicate citation keys, person ids or project ids; `--output` could not be written; or, under `--strict`, any coded diagnostic that the class table does not keep as a warning. The *Diagnostic codes* table below gives the class of each. |
-| `2` | Usage error from the argument parser: a missing or unrecognised flag, or none of `--output` / `--validate` / `--unresolved`. |
+| `0` | Success. `--output` wrote the file; `--validate` found no errors; `--unresolved` reported; `init` wrote every file. |
+| `1` | Error. Configuration file missing, or configuration failed to load — unreadable, a `bib_files[].name` that is absolute or leaves `bib_dir`, a `lab.yaml` of the wrong shape, or a value under `lab` that has no one JSON form; a path the configuration names is not there, or is not a file (not a directory, for `bib_dir`); a people file cannot be read as records; an entry carries `crossref`; `--validate` found unknown project ids or duplicate citation keys, person ids or project ids; `--output` could not be written; `init` refused or could not write a file; or, under `--strict`, any coded diagnostic that the class table does not keep as a warning. The *Diagnostic codes* table below gives the class of each. |
+| `2` | Usage error from the argument parser: a missing or unrecognised flag, or none of `--output` / `--validate` / `--unresolved`; for `init`, an unrecognised flag or more than one `DIR`. |
 
 **Streams and message shapes.** Ordinary reporting goes to **standard
 output**: the counts and unresolved names of
@@ -170,9 +199,9 @@ without depending on English wording. Codes obey three rules:
    | Class | `--validate` | Every other mode | Codes |
    |---|---|---|---|
    | **Fatal at load** | `Error loading configuration: <CODE> …` (`Error: <CODE> …` for `CONFIG-NOT-FOUND`) on standard error; exits `1` before anything is compiled, so there is no report. | The same. | `CONFIG-BIB-FILE-ABSOLUTE`, `CONFIG-BIB-FILE-OUTSIDE-BIB-DIR`, `CONFIG-NOT-A-MAPPING`, `CONFIG-KEY-MISSING`, `CONFIG-TYPE-INVALID`, `CONFIG-VALUE-NOT-JSON`, `CONFIG-KEY-REPEATED`, `CONFIG-NOT-FOUND`, `CONFIG-UNREADABLE` |
-   | **Fatal** | Listed under `Bibliography errors` and counted; exits `1`. | Written to standard error unprefixed; exits `1`, and `--output` writes nothing. | `BIB-CROSSREF-UNSUPPORTED`, `BIB-ENCODING-INVALID`, `CONFIG-FILE-NOT-FOUND`, `CONFIG-PATH-WRONG-KIND`, `PEOPLE-YAML-INVALID`, `PEOPLE-NOT-A-LIST`, `PEOPLE-FIELD-MISSING`, `PROJECTS-YAML-INVALID`, `PROJECTS-NOT-A-LIST`, `PROJECTS-FIELD-MISSING`, `COLLABORATORS-YAML-INVALID`, `COLLABORATORS-NOT-A-LIST`, `COLLABORATORS-FIELD-MISSING`, `RECORD-KEY-REPEATED`, `OUTPUT-WRITE-FAILED` |
+   | **Fatal** | Listed under `Bibliography errors` and counted; exits `1`. | Written to standard error unprefixed; exits `1`, and `--output` writes nothing. | `BIB-CROSSREF-UNSUPPORTED`, `BIB-ENCODING-INVALID`, `CONFIG-FILE-NOT-FOUND`, `CONFIG-PATH-WRONG-KIND`, `PEOPLE-YAML-INVALID`, `PEOPLE-NOT-A-LIST`, `PEOPLE-FIELD-MISSING`, `PROJECTS-YAML-INVALID`, `PROJECTS-NOT-A-LIST`, `PROJECTS-FIELD-MISSING`, `COLLABORATORS-YAML-INVALID`, `COLLABORATORS-NOT-A-LIST`, `COLLABORATORS-FIELD-MISSING`, `RECORD-KEY-REPEATED`, `OUTPUT-WRITE-FAILED`, `INIT-FILE-EXISTS`, `INIT-PATH-WRONG-KIND`, `INIT-PATH-OUTSIDE-DIR`, `INIT-WRITE-FAILED` |
    | **Validation error** | Listed under `Bibliography errors` and counted; exits `1`. | Prefixed `Warning: ` on standard error; the run continues and exits `0`. | `BIB-DUPLICATE-KEY`, `RESOLVE-PROJECT-UNKNOWN`, `PEOPLE-ID-DUPLICATE`, `PROJECTS-ID-DUPLICATE` |
-   | **Warning** | Listed under `Warnings`; not counted, and does not change the exit code. | Prefixed `Warning: ` on standard error; the run continues. | `BIB-YEAR-MISSING`, `BIB-YEAR-INVALID`, `BIB-DOI-INVALID`, `BIB-OTHERS-NOT-LAST`, `BIB-STRING-UNDEFINED`, `BIB-SYNTAX-ERROR`, `BIB-BRACE-MISMATCH`, `BIB-VENUE-MISSING`, `BIB-ENTRY-TYPE-UNSUPPORTED`, `LATEX-COMMAND-UNKNOWN`, `ID-GROUPING-SPANS-SPELLINGS`, `ID-GROUPING-INITIALS-AMBIGUOUS`, `RESOLVE-AMBIGUOUS-NAME`, `RESOLVE-SUGGESTION`, `RESOLVE-COLLABORATOR-ALIAS-IS-MEMBER`, `PEOPLE-ALIAS-AMBIGUOUS`, `PEOPLE-ROLE-INVALID`, `PEOPLE-STATUS-INVALID`, `PROJECTS-STATUS-INVALID`, `CONFIG-LAB-NAME-MISSING`, `CONFIG-KEY-UNKNOWN`, `RECORD-KEY-UNKNOWN`, `RECORD-TYPE-INVALID`, `CONFIG-BIB-FILES-MISSING`, `BIB-PARSER-MESSAGE`, `LATEX-CONVERSION-FAILED`, `TEXT-CONTROL-CHARACTER`, `BIB-WRITE-BACK-FAILED`, `BIB-STRING-REDEFINED`, `ID-GROUPING-AMBIGUOUS-DECLARED`, `RESOLVE-UNRESOLVED-NAME` |
+   | **Warning** | Listed under `Warnings`; not counted, and does not change the exit code. | Prefixed `Warning: ` on standard error; the run continues. | `BIB-YEAR-MISSING`, `BIB-YEAR-INVALID`, `BIB-DOI-INVALID`, `BIB-OTHERS-NOT-LAST`, `BIB-STRING-UNDEFINED`, `BIB-SYNTAX-ERROR`, `BIB-BRACE-MISMATCH`, `BIB-COMMENTED-COMMAND-READ`, `BIB-VENUE-MISSING`, `BIB-ENTRY-TYPE-UNSUPPORTED`, `LATEX-COMMAND-UNKNOWN`, `ID-GROUPING-SPANS-SPELLINGS`, `ID-GROUPING-INITIALS-AMBIGUOUS`, `RESOLVE-AMBIGUOUS-NAME`, `RESOLVE-SUGGESTION`, `RESOLVE-COLLABORATOR-ALIAS-IS-MEMBER`, `PEOPLE-ALIAS-AMBIGUOUS`, `PEOPLE-ROLE-INVALID`, `PEOPLE-STATUS-INVALID`, `PROJECTS-STATUS-INVALID`, `CONFIG-LAB-NAME-MISSING`, `CONFIG-KEY-UNKNOWN`, `RECORD-KEY-UNKNOWN`, `RECORD-TYPE-INVALID`, `CONFIG-BIB-FILES-MISSING`, `BIB-PARSER-MESSAGE`, `LATEX-CONVERSION-FAILED`, `LINK-SCHEME-UNSUPPORTED`, `TEXT-CONTROL-CHARACTER`, `BIB-WRITE-BACK-FAILED`, `BIB-STRING-REDEFINED`, `ID-GROUPING-AMBIGUOUS-DECLARED`, `RESOLVE-UNRESOLVED-NAME` |
 
    The same code always carries the same class. What varies with the mode is
    how the run reacts to it, which is why the class is not in the code, and
@@ -220,10 +249,12 @@ Codes in use:
 | `CONFIG-LAB-NAME-MISSING` | The `lab` header declares no `name`. A `lab` that is not a mapping at all is a different condition and is not reported under this code. A warning. |
 | `BIB-YEAR-INVALID` | An entry's `year` is present but is not an unsigned run of the ASCII digits `0`–`9` (`sslabdata.parsers.bibtex.YEAR_DIGITS`), such as `in press`, or `-5`, `+2020`, `2_020` and full-width `２０２０`, which Python's `int()` would read as numbers. The work is emitted with `year: null` and sorts last, as one with no year does. A warning. |
 | `BIB-DOI-INVALID` | An entry's `doi` is a DOI resolver URL with nothing after it, such as `https://doi.org/` (`sslabdata.parsers.bibtex.DOI_RESOLVERS`), so it names no DOI. Located at `<file>:<key>:doi`, naming the value. The work gets no DOI identifier and no link of kind `doi`, rather than an empty one; the entry is kept. A `doi` that is empty or blank is read as absent, and is not reported. A warning. |
+| `LINK-SCHEME-UNSUPPORTED` | A link in `work.links` whose URL scheme is not `http`, `https` or `mailto` (`sslabdata.parsers.bibtex.LINK_SCHEMES`), such as `javascript:`, `data:` or `vbscript:`, which a renderer escaping the document (§2) should refuse to turn into a link. The scheme is the one Python's URL parser reads (`urllib.parse.urlsplit()`, in `sslabdata.parsers.bibtex.url_scheme()`) once surrounding whitespace is off, compared without regard to case; the parser drops a tab or line break anywhere in the URL first, as a browser does, so `java<tab>script:` is `javascript`. A URL with no scheme is a relative path and is not reported; that includes a protocol-relative `//host/path`, which takes the scheme of the page that links it. A scheme of one letter is a Windows drive, read by Windows rules as `sslabdata.config` reads one (`PureWindowsPath`), and not a scheme: `C:/papers`, `C:\papers` and the drive-relative `c:papers` are local paths and are not reported. No registered scheme is one letter long. Every link is checked, whether the entry wrote it (`url`, `video`, `pdf`) or sslabdata built it (`doi`, `arxiv`, and `pdf` from `pdf_base_url`). Located at `<file>:<key>:<field>`, the field the link came from, or at `<file>:<key>:` for the PDF link `pdf_base_url` builds, which no field of the entry wrote; the prose names the link's kind, which for `url` can be `video`, and the URL. Once per link. A person's `website` and `photo`, a project's `website` and `image`, and everything under `lab` are fields, not links, and are not checked. **The link is emitted unchanged**: this code only reports it. A warning. |
 | `BIB-OTHERS-NOT-LAST` | An `author` or `editor` list has `and others` somewhere other than at its end, the one place BibTeX reads it as "et al.". It names nobody there either, so it is dropped as a terminal one is, and the names around it are kept in their order, with `position` counting only them. Located at `<file>:<key>:author` or `:editor`, once per list however many times it occurs. A terminal `and others` is not reported. A warning. |
 | `BIB-STRING-UNDEFINED` | A field value names an `@string` macro that nothing defined earlier in the same file. Located at the entry and field that use it, and naming the macro. It is read as empty, as BibTeX reads it, and the entry and its neighbours are kept. A macro used inside another `@string` definition is located at the file alone. A warning. |
-| `BIB-STRING-REDEFINED` | One or more `@string` macros are defined more than once. One line per run, however many files and macros: the count, the macros and every redefinition as `file:line` (§7). Only definitions the parser reads count, so one inside an `@comment` group does not, while a well-formed `@string{…}` on a `%` line does: the parser reads it, and it changes the macro's value. Whether it should be read is #78. The last definition is used, as in BibTeX. A warning in every mode, including under `--strict`. |
-| `BIB-SYNTAX-ERROR` | Text the BibTeX parser cannot read. Inside an entry, located at that entry and at the field the parser was reading or had just read, which is where an unclosed brace or quote leaves it, or with the field left empty when the error comes before any field; the entry is kept as far as it was read, so that value may hold text meant for later fields. Outside any entry — an `@` that begins no well-formed command — located at the file alone and skipped. A syntax error the parser library raises on a `%` line outside any entry — prose that mentions `@article`, say, which the library reads as the start of a command — is not reported (`sslabdata.parsers.bibtex._on_comment_line()`), so the prose `tests/COVERAGE.md` rows `structure.comment_lines` and `structure.comment_mentions_command` describe says nothing. A **well-formed** command on such a line is read, as in classic BibTeX, which has no `%` comment outside an entry: `% @article{hidden, …}` is an entry. Whether it should be is #78. The prose gives the line. A warning. |
+| `BIB-STRING-REDEFINED` | One or more `@string` macros are defined more than once. One line per run, however many files and macros: the count, the macros and every redefinition as `file:line` (§7). Only definitions the parser reads count, so one inside an `@comment` group does not, while a well-formed `@string{…}` on a `%` line does: it is read, as every well-formed command on such a line is, it changes the macro's value, and it also draws `BIB-COMMENTED-COMMAND-READ`. The last definition is used, as in BibTeX. A warning in every mode, including under `--strict`. |
+| `BIB-SYNTAX-ERROR` | Text the BibTeX parser cannot read. Inside an entry, located at that entry and at the field the parser was reading or had just read, which is where an unclosed brace or quote leaves it, or with the field left empty when the error comes before any field; the entry is kept as far as it was read, so that value may hold text meant for later fields. Outside any entry — an `@` that begins no well-formed command — located at the file alone and skipped. A syntax error the parser library raises on a `%` line outside any entry — prose that mentions `@article`, say, which the library reads as the start of a command — is not reported (`sslabdata.parsers.bibtex._on_comment_line()`), so the prose `tests/COVERAGE.md` rows `structure.comment_lines` and `structure.comment_mentions_command` describe says nothing. A **well-formed** command on such a line is read, and reported under `BIB-COMMENTED-COMMAND-READ`. The prose gives the line. A warning. |
+| `BIB-COMMENTED-COMMAND-READ` | A well-formed command on a line that starts with `%` outside any entry. It is read, as classic BibTeX reads it, which has no `%` comment outside an entry: `% @article{hidden, …}` is an entry, and becomes a work, a `% @string{…}` defines its macro, and a `% @preamble{…}` is read as any `@preamble` is. Each command read from such a line is reported once, so a user who meant to comment it out is told it was read (`sslabdata.parsers.bibtex._commented_commands()`): an entry located at its key, and an `@string` or `@preamble` at the file alone, naming the macro. The prose gives the line. An `@string` counts as `BIB-STRING-REDEFINED` counts it, when its definition was read in full. Prose on a `%` line that is no well-formed command is not one, and says nothing (`BIB-SYNTAX-ERROR`); an `@comment{…}` group, or a line with no `@`, leaves an entry out. A warning. |
 | `BIB-BRACE-MISMATCH` | An entry that BibTeX's brace matching reads differently from how it was written, with no syntax error: one opening brace too many reads the next field into a value, and one closing brace too many ends the entry, so the fields after it are not read. Braces are matched as BibTeX matches them, `\{` and `\}` included, and the entry is kept as read; this code only reports it. Two shapes are looked for (`sslabdata.parsers.bibtex._Parser._check_braces()`), and nothing else, so a well-formed file never draws one: a value holding `, <name> = {` or `, <name> = "`, located at `<name>`, the field read into it, and naming the value's field; and text after the entry's closing brace on the line it ends on, other than a `%` comment or the next `@` command, located at the first field lost when that text is shaped `, <name> =`, and otherwise at the entry's last field read, whose text it is, naming the line. Once per entry, located at the first field whose text did not arrive as written. An entry with a `BIB-SYNTAX-ERROR` is not checked: that code already says its values may hold text meant for later fields. A `BIB-STRING-UNDEFINED` does not say so, and an entry with one is checked: in `title = {\} # w}`, BibTeX counts `\}` as a brace, so `w` is read as a macro and the next `}` ends the entry. A warning. |
 | `BIB-VENUE-MISSING` | An `@article` has no `journal`, or an `@inproceedings` has no `booktitle` (`sslabdata.parsers.bibtex.REQUIRED_CONTAINER`). No other entry type is checked. A field present but empty counts as missing. The entry is kept, and its venue is read by the usual rule from any other container field it carries, or is `null`. A warning. |
 | `BIB-ENTRY-TYPE-UNSUPPORTED` | An entry's type is not one sslabdata documents. Those are `@article`, `@inproceedings`, `@conference`, `@proceedings`, `@incollection`, `@inbook`, `@book`, `@phdthesis`, `@mastersthesis`, `@techreport`, `@manual` and `@misc` (`sslabdata.parsers.bibtex.SUPPORTED_TYPES`); `@unpublished` and `@booklet`, for two, are not. Located at `<file>:<key>:entry_type`. The entry is kept, and its venue is read by the field rules alone. A warning. |
@@ -246,7 +277,7 @@ Codes in use:
 | `RECORD-KEY-REPEATED` | A key is given twice in one mapping of a people, projects or collaborators file, which YAML alone would read as its last value, silently dropping the first. Every YAML file sslabdata reads is read with one loader that finds these (`sslabdata.config.YAMLLoader`). Keys are compared as YAML reads them, so `1` and `0x1` are one key. A merge key (`<<`) is not a repeat: the keys it merges in are overridden by the mapping's own, as YAML merge keys are defined. One code for all three files. Located at `<file>:<id>:<key>` (a collaborator's name for its id), with the path below the record's top level joined by `.` and a list member's index in brackets; the record is named by nothing when the repeated key is its `id` (a collaborator's `name`), and a repeat outside any record is located at `<file>::<path>`. The prose names the key and both lines. Every repeat is reported; the record is not loaded, and the run is fatal, as for a missing field: which value was meant is not sslabdata's to guess. |
 | `CONFIG-NOT-A-MAPPING` | `lab.yaml` is not a mapping of keys, or is empty. Fatal at load. |
 | `CONFIG-KEY-MISSING` | A required key is absent: `bib_dir`, or the `name` or `category` of a `bib_files` entry (`lab.yaml:bib_files:name`). Fatal at load. |
-| `CONFIG-TYPE-INVALID` | A key has a value of the wrong type: `bib_dir`, `pdf_base_url`, `people_file`, `projects_file` or `collaborators_file` that is not a string, `lab` that is not a mapping, a `lab` key the schema types (`name`, `description`, `institution`, `department`, `website`, `email`, `address` and `logo` are strings, `links` a mapping) whose value is another type or empty, or `bib_files` that is not a list. A `bib_files` entry is a mapping of a string `name` and a string `category` and nothing else: one that is not a mapping, whose `name` or `category` is not a string, or that holds another key is this code too, located at `lab.yaml:bib_files:<field>`. Fatal at load. |
+| `CONFIG-TYPE-INVALID` | A key has a value of the wrong type: `bib_dir`, `pdf_base_url`, `people_file`, `projects_file` or `collaborators_file` that is not a string, `lab` that is not a mapping, a `lab` key the schema types (`name`, `description`, `institution`, `department`, `website`, `email`, `address` and `logo` are strings, `links` a mapping) whose value is another type or empty, or `bib_files` that is not a list. A `bib_files` entry is a mapping of a string `name` and a string `category` and nothing else: one that is not a mapping, whose `name` or `category` is not a string, or that holds another key is this code too, located at `lab.yaml:bib_files:<field>`. A `pdf_base_url` that is empty or whitespace alone names no base and is this code too, at `lab.yaml:pdf_base_url:`, whether it comes from `lab.yaml` or from a `LabDataConfig` built in Python (`sslabdata.config.reject_empty_pdf_base_url()`): as for `CONFIG-FILE-NOT-FOUND`'s empty path, only a key left out, or `None`, means none, here no guessed PDF link. Fatal at load. |
 | `CONFIG-VALUE-NOT-JSON` | A value under `lab`, at any depth and `lab.links` included, that the document cannot carry the same way in both formats: NaN or an infinity, which JSON cannot write; a set (`!!set`), whose order is not stable between runs; binary (`!!binary`); any other type that is not text, a number, a boolean, null, a list or a mapping; or a mapping key that is not a string, which YAML and JSON would write differently. Located at `lab.yaml:lab:<path>`, or at the mapping holding a key that is not a string, with the value or key in the prose. A date or a timestamp is not this code: it is emitted as its ISO 8601 text (`2010-01-01`, `2024-05-01T09:30:00+00:00`), in both formats. Fatal at load, so `--validate` fails wherever `--output` could not write the document. Raised as a `sslabdata.ConfigurationError`. |
 | `CONFIG-KEY-REPEATED` | A key is given twice in one mapping of `lab.yaml`, at any depth, which YAML alone would read as its last value, silently dropping the first. Keys are compared as `RECORD-KEY-REPEATED` compares them, and a merge key (`<<`) is not a repeat. Located at `lab.yaml:<key>:<field>` as rule 1 above locates any key of the file, with the repeated key last (`lab.yaml:lab:name` for a `name` given twice under `lab`, `lab.yaml:people_file:` for a top-level key); the prose names the key and both lines. The first repeat in the file is reported. Fatal at load. Raised as a `sslabdata.ConfigurationError`. |
 | `CONFIG-KEY-UNKNOWN` | `lab.yaml` holds a key sslabdata does not read (`sslabdata.config.KNOWN_KEYS`), such as a misspelt `people_fil`. It is ignored. A warning. |
@@ -257,7 +288,11 @@ Codes in use:
 | `LATEX-CONVERSION-FAILED` | A text field or a name part whose LaTeX the converter could not read at all, or whose conversion left one of the converter's own markers behind — a command that read part of a set-aside URL as its argument, such as an accent written before `\url{…}` (`sslabdata.parsers.latex.latex_to_text()`). Its text is kept as written, with the braces taken off, so it may still hold LaTeX (§2, *Two degraded cases*). Located at the entry and field. A warning. |
 | `TEXT-CONTROL-CHARACTER` | A value read from the input holds a control character (§2, *No string read from the input carries a control character*): a `.bib` field value, located at `<file>:<key>:<field>`, or a YAML scalar, key or value, located as `RECORD-KEY-REPEATED` locates a key in a people, projects or collaborators file and as `CONFIG-KEY-REPEATED` locates one in `lab.yaml`. One line per value, naming each character as `U+XXXX`. The characters are removed and the rest of the value is kept. A warning. |
 | `BIB-WRITE-BACK-FAILED` | An entry that could not be written back out as BibTeX. Its `bibtex` is `null`. Located at `<file>:<key>:bibtex`. A warning. |
-| `OUTPUT-WRITE-FAILED` | `--output` names a destination the operating system will not let sslabdata write: a directory, a path under a file, a directory without write permission, a full disk. Located at the `--output` path alone; the prose is the operating system's reason, naming the path it refused when that is not the destination's own directory. Unprefixed on standard error, with no `Wrote …` line. The write is atomic, so a file already at the path is as it was and no temporary file is left behind. Only `--output` writes, so no other mode reports it. Fatal. |
+| `OUTPUT-WRITE-FAILED` | `--output` names a destination the operating system will not let sslabdata write: a directory, a path under a file, a directory without write permission, a full disk. Located at the `--output` path alone; the prose is the operating system's reason, naming the path it refused when that is not the destination's own directory. Unprefixed on standard error, with no `Wrote …` line. The write is atomic, so a file already at the path is as it was and no temporary file is left behind. Only `--output` writes the document, so no other mode reports it; `init` reports its own writes as `INIT-WRITE-FAILED`. Fatal. |
+| `INIT-FILE-EXISTS` | `sslabdata init` found a file already at a path it writes, and `--force` was not given. Located at that path alone, one line per file. Nothing is written. Fatal. |
+| `INIT-PATH-WRONG-KIND` | `sslabdata init` found something other than a directory at `DIR` or at its `bib` directory, or something other than a regular file or a symlink at a path it writes, such as a directory. Located at that path alone. Nothing is written, with or without `--force`. Fatal. |
+| `INIT-PATH-OUTSIDE-DIR` | A directory `sslabdata init` writes into, `DIR/bib`, resolves outside `DIR` once symlinks are followed, so a file written there would land outside `DIR`. Located at the file's path alone. Nothing is written, with or without `--force`. Fatal. |
+| `INIT-WRITE-FAILED` | `sslabdata init` could not create `DIR` or write one of its files: a directory without write permission, a full disk. Located at that path alone; the prose is the operating system's reason. The file that failed is not left half written, and one already there is as it was; files written before it stay. Fatal. |
 | `CONFIG-NOT-FOUND` | The `--config` file does not exist. Located at that path alone; `Error: CONFIG-NOT-FOUND …` on standard error. Fatal at load. |
 | `CONFIG-UNREADABLE` | The `--config` file exists but cannot be read — not valid YAML, not UTF-8, or a file the operating system will not open — or another input file, such as a `people_file`, exists but the operating system will not open it. Located at the `--config` path alone; the prose is the reading library's own wording, on one line. Fatal at load. |
 | `CONFIG-BIB-FILE-ABSOLUTE` | A `bib_files[].name` is an absolute path, under POSIX or Windows rules. Fatal at load, because the name is emitted as `work.source.file`, which is promised never to be absolute (§5). Raised as a `sslabdata.ConfigurationError`, which the Python API paragraphs below say more about. |
@@ -517,7 +552,8 @@ converts nor checks them:
   `edition` and `howpublished`, which are outside `TEXT_FIELDS` and are
   emitted as the entry wrote them.
 - **Every identifier** in `identifiers`, and the `url` of a link whose
-  `origin` is `input`.
+  `origin` is `input`. Of a link's `url`, only the scheme is checked, and it
+  is emitted as written whatever the check finds (`LINK-SCHEME-UNSUPPORTED`).
 
 For these the plain-Unicode rule is a **requirement on the input, not a
 guarantee sslabdata enforces**. If `people.yaml` says `name: "<b>Alice</b>"`,
@@ -551,7 +587,7 @@ rule does not apply to the input itself — only to whatever it produces.
 | The citation key and the entry type | Become `bib_id` (and `source.key`) and `entry_type` (`entry_fields()`); see heading 4. |
 | `person.aliases` | Read for matching by `sslabdata.resolver.match()`, never emitted — `Person.to_dict()` has no `aliases` key. |
 | `collaborators_file` entries | A list of `{name, aliases}` read by `sslabdata.loaders.load_collaborators()`. Read only to decide which unresolved authorships share one `collaborators` grouping (§5); never emitted as such and never a source of `person_id`. |
-| `bib_dir`, `people_file`, `projects_file`, `collaborators_file`, `pdf_base_url` | Configuration. Never emitted; `pdf_base_url` survives only inside the constructed PDF link. `bib_files[].name` **is** emitted, as `work.source.file`, and is therefore checked (`sslabdata.config.is_absolute_path()`, §5). |
+| `bib_dir`, `people_file`, `projects_file`, `collaborators_file`, `pdf_base_url` | Configuration. Never emitted; `pdf_base_url` survives only inside the constructed PDF link, and leaving it out turns that guess off (§5). `bib_files[].name` **is** emitted, as `work.source.file`, and is therefore checked (`sslabdata.config.is_absolute_path()`, §5). |
 | Any BibTeX field named nowhere in this table or heading 1 — `keywords`, `annote`, `language` and the rest | Not interpreted by sslabdata outside the `bibtex` record. `entry_fields()` copies it and `format_bibtex()` serializes it, but nothing reads its value, so it affects no other property (§5). |
 
 The fields named in that table and in heading 1 are the complete set sslabdata
@@ -755,7 +791,7 @@ sslabdata's own output as input, and a wrong derivation becomes permanent.
 | `work.links` | **Derived** — a map from kind to link records, built from the entry's `url`, `video` and `pdf`, from `pdf_base_url` and from the identifiers above (`build_links()`). See below. |
 | `work.project_ids` | Input — the `project` field, split on commas (`parse_project_ids()`). |
 | `work.bibtex` | **Derived** — the entry re-serialized as BibTeX, or `null` when that failed (`format_bibtex()`). See below. |
-| `author.given`, `von`, `family`, `suffix`, `literal` | Input — the parts BibTeX split the name into, converted from LaTeX, with an equal-contribution marker removed (`person_name_parts()`). An entry writing `Brown, B.` yields `given: "B."`, and that is correct, not a gap. |
+| `author.given`, `von`, `family`, `suffix`, `literal` | Input — the parts BibTeX split the name into, converted from LaTeX, with an equal-contribution marker removed (`person_name_parts()`). A spaced marker that BibTeX split between the particle and the surname is joined again, and those two parts are split as BibTeX splits the name with the marker unspaced (`_joined_groups()`). So is one that runs from the given name into the rest in a name written given name first, `Bob Brown\textsuperscript {*}`, whose words are then read again as BibTeX reads them with the marker unspaced (`_crosses_given_name()`). An entry writing `Brown, B.` yields `given: "B."`, and that is correct, not a gap. |
 | `author.name` | **Derived** — the parts joined in reading order (`readable_name()`). *A readable form of the input name, not a citation form*: it does not abbreviate, expand or normalise. |
 | `author.position` | **Derived** — where the authorship sits in its work's list, 1-based, counting only the names that reach the document. |
 | `author.person_id` | **Derived** — the resolver's match against `people_file` (`sslabdata.resolver.resolve_authors()`): on the structured full name, then — only for a name that is itself abbreviated — on a declared alias, and never when the name fits more than one person or only nearly matches. See *How a name is matched* below. |
@@ -898,7 +934,14 @@ or `missing` and a remote one yields `unchecked`; an entry's own `pdf` is
 `unchecked` whatever the base. `verification` is `{status}` and records no
 time. Three states replace a null: "no base configured" is no link at all for an entry without a `pdf`
 field, "the file is not there" is `missing`, and "nobody has looked" is
-`unchecked`. Verifying a remote link is #20.
+`unchecked`. Nothing in sslabdata checks a remote link, since it makes no
+network calls.
+
+**`pdf_base_url` is the switch for guessed PDF links.** It is read for
+nothing else, so a `lab.yaml` without it guesses no PDF link, and a work gets
+one only from its own `pdf` field. There is no separate key to turn guessing
+off. An empty or blank `pdf_base_url` is not that switch: it is
+`CONFIG-TYPE-INVALID`.
 
 A link does **not** name the identifier it was built from. That is redundant
 with its kind and its origin, and it would be a cross-record constraint JSON
@@ -1095,6 +1138,19 @@ resolves, because GitHub redirects `labdata` to `sslabdata`. v3's `blob/main`
 `$id` does not resolve, as above. v5's `$id`, title and descriptions say
 `sslabdata`.
 
+**The input schemas are versioned apart from the document.**
+`schema/input/v1/` holds a JSON Schema for each input file: `lab.schema.json`,
+`people.schema.json`, `projects.schema.json` and `collaborators.schema.json`.
+They describe what the loaders accept; the loaders stay the authority, and
+the diagnostic codes above report what a schema cannot see. The input format
+and the document change for different reasons, so the input schemas carry
+their own version rather than `schema_version`. They follow the same rules:
+a published input schema is never edited, any change to one is a new
+version at a new path, and its `$id` is a pinned tag URL,
+`https://raw.githubusercontent.com/siddhss5/sslabdata/input-schema-v1/schema/input/v1/<file>.schema.json`,
+whose `input-schema-v1` tag is created when this version ships and is never
+moved.
+
 **Version history.** What each `schema_version` changed is in
 [`CHANGELOG.md`](CHANGELOG.md).
 
@@ -1126,7 +1182,7 @@ any entry uses them, so the corpus does not distinguish the two readings.
 A redefinition is never silent. `sslabdata.parsers.bibtex._redefined_macros()`
 finds every definition of a macro after its first — among the definitions
 the parser itself reads, so an `@string` inside an `@comment` group is not
-counted, and a line number counts lines as the parser does, after a byte
+counted, one on a `%` line is (`BIB-COMMENTED-COMMAND-READ`), and a line number counts lines as the parser does, after a byte
 order mark and with CRLF read as one line end — and `parse_all_works()`
 reports all of a run's in **one line**, under `BIB-STRING-REDEFINED`
 (`redefined_summary()`; `tests/COVERAGE.md` row `strings.redefined_report`):

{sslabdata-3.0.0 → sslabdata-3.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sslabdata"
-version = "3.0.0"
+version = "3.1.0"
 description = "Renderer-agnostic academic lab data assembler: BibTeX + YAML → structured data"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -57,9 +57,10 @@ Changelog = "https://github.com/siddhss5/sslabdata/blob/main/CHANGELOG.md"
 requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
-# The current output schema is public wheel data, installed at
-# sslabdata/schema/v5/output.schema.json. The package directory is mapped onto
-# the repository's schema/ directory so the frozen file has one copy and one
+# The current output schema and input schemas are public wheel data, installed
+# at sslabdata/schema/v5/output.schema.json and
+# sslabdata/schema/input/v1/*.schema.json. The package directory is mapped onto
+# the repository's schema/ directory so each frozen file has one copy and one
 # path; earlier versions stay in the sdist only. schema/__init__.py makes the
 # mapped directory a regular package, which editable installs need to resolve.
 [tool.setuptools]
@@ -70,7 +71,9 @@ packages = ["sslabdata", "sslabdata.parsers", "sslabdata.schema"]
 "sslabdata.schema" = "schema"
 
 [tool.setuptools.package-data]
-"sslabdata.schema" = ["v5/output.schema.json"]
+"sslabdata.schema" = ["v5/output.schema.json", "input/v1/*.schema.json"]
+# The starting point `sslabdata init` copies.
+"sslabdata" = ["templates/init/*.yaml", "templates/init/bib/*.bib"]
 
 [tool.mypy]
 files = ["sslabdata"]

sslabdata-3.1.0/schema/input/v1/collaborators.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/siddhss5/sslabdata/input-schema-v1/schema/input/v1/collaborators.schema.json",
+  "title": "sslabdata collaborators file",
+  "description": "The file lab.yaml names as collaborators_file: co-authors outside the lab whose spellings are grouped together, one record each. A record never makes anyone a lab member. It describes what sslabdata's loader accepts; the loader stays the authority, and reports each problem under a code in SPEC.md, Diagnostic codes. A record key not listed here is reported as RECORD-KEY-UNKNOWN and ignored, so it is allowed. Published input schemas are immutable: this one is served from the input-schema-v1 tag, which is created when this version ships and is never moved (SPEC.md §6).",
+  "type": ["array", "null"],
+  "items": { "$ref": "#/$defs/collaborator" },
+  "$defs": {
+    "nonEmptyString": { "type": "string", "pattern": "\\S" },
+    "collaborator": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": true,
+      "properties": {
+        "name": { "$ref": "#/$defs/nonEmptyString" },
+        "aliases": {
+          "description": "Other spellings of the name, grouped with it.",
+          "type": ["array", "null"],
+          "items": { "$ref": "#/$defs/nonEmptyString" }
+        }
+      }
+    }
+  }
+}

sslabdata-3.1.0/schema/input/v1/lab.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/siddhss5/sslabdata/input-schema-v1/schema/input/v1/lab.schema.json",
+  "title": "sslabdata lab.yaml",
+  "description": "The configuration file sslabdata is run with (--config). It describes what sslabdata's loader accepts; the loader stays the authority, and reports each problem under a code in SPEC.md, Diagnostic codes. A key not listed here is reported as CONFIG-KEY-UNKNOWN and ignored, so it is allowed. Published input schemas are immutable: this one is served from the input-schema-v1 tag, which is created when this version ships and is never moved (SPEC.md §6).",
+  "type": "object",
+  "required": ["bib_dir"],
+  "additionalProperties": true,
+  "properties": {
+    "lab": {
+      "description": "The lab header, copied into the document's lab unchanged (SPEC.md §5). The keys below are typed; any other key is allowed and copied through. sslabdata warns when it declares no name (CONFIG-LAB-NAME-MISSING).",
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "institution": { "type": "string" },
+        "department": { "type": "string" },
+        "website": { "type": "string" },
+        "email": { "type": "string" },
+        "address": { "type": "string" },
+        "logo": { "type": "string" },
+        "links": { "type": "object" }
+      }
+    },
+    "site": {
+      "description": "Read by renderers, not by sslabdata, and accepted without being checked."
+    },
+    "bib_dir": {
+      "description": "The directory the bib_files names are under, relative to the directory sslabdata is run from.",
+      "type": "string"
+    },
+    "bib_files": {
+      "description": "The .bib files to read. sslabdata warns when there are none (CONFIG-BIB-FILES-MISSING).",
+      "type": ["array", "null"],
+      "items": {
+        "type": "object",
+        "required": ["name", "category"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "description": "A name under bib_dir, emitted as work.source.file: never absolute, and never leaving bib_dir (SPEC.md §5).",
+            "type": "string"
+          },
+          "category": {
+            "description": "Emitted as the category of every work in this file.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "pdf_base_url": {
+      "description": "A work with no pdf field gets this URL plus its citation key as its pdf link. Leave it out to guess no pdf links; an empty or blank value is an error.",
+      "type": ["string", "null"],
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "people_file": {
+      "description": "The people file (people.schema.json), relative to the directory sslabdata is run from.",
+      "type": ["string", "null"]
+    },
+    "projects_file": {
+      "description": "The projects file (projects.schema.json), relative to the directory sslabdata is run from.",
+      "type": ["string", "null"]
+    },
+    "collaborators_file": {
+      "description": "The external co-authors file (collaborators.schema.json), relative to the directory sslabdata is run from.",
+      "type": ["string", "null"]
+    }
+  }
+}

sslabdata-3.1.0/schema/input/v1/people.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/siddhss5/sslabdata/input-schema-v1/schema/input/v1/people.schema.json",
+  "title": "sslabdata people file",
+  "description": "The file lab.yaml names as people_file: a list of lab members and alumni, one record each. It describes what sslabdata's loader accepts; the loader stays the authority, and reports each problem under a code in SPEC.md, Diagnostic codes. A record key not listed here is reported as RECORD-KEY-UNKNOWN and ignored, so it is allowed. What each field becomes in the document is in SPEC.md §5. Published input schemas are immutable: this one is served from the input-schema-v1 tag, which is created when this version ships and is never moved (SPEC.md §6).",
+  "type": ["array", "null"],
+  "items": { "$ref": "#/$defs/person" },
+  "$defs": {
+    "nonEmptyString": { "type": "string", "pattern": "\\S" },
+    "optionalString": { "type": ["string", "null"] },
+    "optionalYear": { "type": ["integer", "null"] },
+    "person": {
+      "type": "object",
+      "required": ["id", "name", "role"],
+      "additionalProperties": true,
+      "properties": {
+        "id": {
+          "description": "The person's id, unique in the file (PEOPLE-ID-DUPLICATE).",
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "name": { "$ref": "#/$defs/nonEmptyString" },
+        "aliases": {
+          "description": "Other spellings of the name, used to match BibTeX authors and never emitted.",
+          "type": ["array", "null"],
+          "items": { "$ref": "#/$defs/nonEmptyString" }
+        },
+        "role": {
+          "description": "Any non-empty string; there is no list of roles (PEOPLE-ROLE-INVALID).",
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "status": {
+          "description": "current when absent (PEOPLE-STATUS-INVALID).",
+          "enum": ["current", "alumni"]
+        },
+        "photo": { "$ref": "#/$defs/optionalString" },
+        "website": { "$ref": "#/$defs/optionalString" },
+        "email": { "$ref": "#/$defs/optionalString" },
+        "co_advisor": { "$ref": "#/$defs/optionalString" },
+        "start_year": { "$ref": "#/$defs/optionalYear" },
+        "end_year": { "$ref": "#/$defs/optionalYear" },
+        "degree": { "$ref": "#/$defs/optionalString" },
+        "thesis_title": { "$ref": "#/$defs/optionalString" },
+        "current_position": { "$ref": "#/$defs/optionalString" }
+      }
+    }
+  }
+}

sslabdata-3.1.0/schema/input/v1/projects.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/siddhss5/sslabdata/input-schema-v1/schema/input/v1/projects.schema.json",
+  "title": "sslabdata projects file",
+  "description": "The file lab.yaml names as projects_file: a list of research projects, one record each. It describes what sslabdata's loader accepts; the loader stays the authority, and reports each problem under a code in SPEC.md, Diagnostic codes. A record key not listed here is reported as RECORD-KEY-UNKNOWN and ignored, so it is allowed. What each field becomes in the document is in SPEC.md §5. Published input schemas are immutable: this one is served from the input-schema-v1 tag, which is created when this version ships and is never moved (SPEC.md §6).",
+  "type": ["array", "null"],
+  "items": { "$ref": "#/$defs/project" },
+  "$defs": {
+    "nonEmptyString": { "type": "string", "pattern": "\\S" },
+    "optionalString": { "type": ["string", "null"] },
+    "project": {
+      "type": "object",
+      "required": ["id", "title"],
+      "additionalProperties": true,
+      "properties": {
+        "id": {
+          "description": "The project's id, unique in the file (PROJECTS-ID-DUPLICATE). A work's project field names it.",
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "title": { "$ref": "#/$defs/nonEmptyString" },
+        "description": { "$ref": "#/$defs/optionalString" },
+        "website": { "$ref": "#/$defs/optionalString" },
+        "image": {
+          "description": "A URL or a site path, carried as plain text.",
+          "$ref": "#/$defs/optionalString"
+        },
+        "status": {
+          "description": "active when absent (PROJECTS-STATUS-INVALID).",
+          "enum": ["active", "completed"]
+        }
+      }
+    }
+  }
+}

{sslabdata-3.0.0 → sslabdata-3.1.0}/sslabdata/__init__.py

@@ -37,4 +37,4 @@ __all__ = [
     "export_to_yaml",
     "export_to_json",
 ]
-__version__ = "3.0.0"
+__version__ = "3.1.0"

{sslabdata-3.0.0 → sslabdata-3.1.0}/sslabdata/assembler.py

@@ -17,7 +17,8 @@ from pathlib import Path
 from typing import Dict, List, Optional, Tuple
 
 from .config import (
-    LabDataConfig, reject_absolute_name, reject_name_outside_bib_dir,
+    LabDataConfig, reject_absolute_name, reject_empty_pdf_base_url,
+    reject_name_outside_bib_dir,
 )
 from .diagnostics import (
     ERROR, Diagnostic, diagnostic, in_report_order, severity,
@@ -359,6 +360,7 @@ def assemble_result(config: LabDataConfig) -> AssemblyResult:
     for bib_file in config.bib_files:
         reject_name_outside_bib_dir(getattr(bib_file, 'name', None),
                                     config.bib_dir)
+    reject_empty_pdf_base_url(config.pdf_base_url)
 
     found: List[Diagnostic] = []
     source = config.path or 'lab.yaml'