docs: detail SPDX compatibility for `license` key

Metadata

Project: craft-application
Number: #1022
Type: issue
State: open
Author: medubelko
Labels: Status: Triaged Type: Documentation
Created: 2026-03-09 08:33 PM UTC
Updated: 2026-03-12 04:48 PM UTC
Closed: —

Current evaluation

Maintainer-filed docs request to state in the `license` field docs that values are SPDX expressions, note AND/OR support, add conjunctive examples, and link the SPDX spec; triaged, partially addressed, still open

Suggested action: keep open

Reason: The issue is labelled 'Status: Triaged' and the maintainer narrowed scope in the jahn-junior quote ("the docstring I linked could still be more helpful... we can include an example for conjunctive licenses and use a nicer link for the spec"). The code confirms this is still undone: craft_application/models/project.py:177-183 only links SPDX 2.1 expressions and the spec PDF, and constraints.py:227-235 still carries the bare description "SPDX license string." with no AND/OR mention or spec link. Impact is limited to documentation quality, but an unresolved decision (medubelko: "Should we override the text in the Rockcraft docs?", noting lengau that only Rockcraft uses SpdxLicenseStr) is still blocking full closure.

Evaluated by: mr-cal-bot

Impact: 22 Quick Win: 13 Complexity: 18 Confidence: 84 Actionability: 74

Issue body

### What needs to get done ## Situation The `license` key complies with SPDX, but the [field's docs](https://github.com/canonical/craft-application/blob/main/craft_application/models/constraints.py#L225) don't state that the value is a license _expression_, nor the constraints. Users might understand it to be a plain a string. ## Request In the `license` docstring: - Mention that it's a compliant SPDX expression. - Indicate that `AND` and `OR` are supported. - Provide richer examples of the expression syntax. - Link to the [full SPDX spec](https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions). ### Why it needs to get done The constraints of the key aren't clear in the existing docs.

Evaluation history

Date	Model	Scores	Action	Summary
2026-10-02 05:32 PM UTC	stealth/space-bunny-alpha	Impact: 22 Quick Win: 13 Complexity: 18 Confidence: 84 Actionability: 74	keep open	Maintainer-filed docs request to state in the `license` field docs that values are SPDX expressions, note AND/OR support, add conjunctive examples, and link the SPDX spec; triaged, partially addressed, still open
2026-09-20 11:27 PM UTC	qwen/qwen3.6-35b-a3b	Impact: 30 Quick Win: 19 Complexity: 20 Confidence: 85 Actionability: 80	keep open	Documentation improvement: enhance license field docstrings to clarify SPDX expression syntax, supported operators, and link to full SPDX spec.
2026-09-01 03:37 AM UTC	qwen/qwen3.8-27b	Impact: 35 Quick Win: 30 Staleness: 55 Complexity: 15 Confidence: 75 Support Request: 10	keep open	Documentation improvement for the `license` key to clarify it accepts SPDX expressions, mention AND/OR support, provide richer examples, and link to the full SPDX spec. Partially addressed: docstring now says 'SPDX expression' and links to spec, but AND/OR mention and richer examples are still missing.
2026-07-22 12:15 PM UTC	qwen/qwen3.6-35b-a3b	Staleness: 45 Complexity: 15 Confidence: 85 Support Request: 0	keep open	Documentation update needed to clarify that the license field uses SPDX expressions, including syntax examples and spec links. Currently under discussion among maintainers regarding docstring location and downstream consistency.
2026-07-08 08:57 PM UTC	qwen3.6-35b-a3b-mtp-q6	Staleness: 45 Complexity: 15 Confidence: 85 Support Request: 0	keep open	Documentation update to clarify the license key uses SPDX expressions, including syntax constraints and examples. Currently under maintainer discussion regarding docstring location and downstream overrides.

Update history

No update history recorded yet.

Related issues

No related issues found above the similarity threshold.