feat: add license information to the api #1482

jcpitre · 2025-11-25T18:24:04Z

Summary:
closes #1345
Added some license related fields to the feeds response, namely:

source_info->license_id
source_info->license_is_spdx
source_info->license_notes

Added the /v1/licenses endpoint (see examples below).

Still to be done:

Return the content_txt and content_html in a separate endpoint call. Suggestion:
Add a include_license_content parameter to the /v1/licenses/{id} endpoint.
license_rules part of the response /v1/licenses contains the name of the rule. Maybe we want to use the label instead
license_rules could have its own endpoint?

AI summary

This pull request adds full support for managing and exposing license information for feeds in the API. It introduces new endpoints for license retrieval, updates feed models and test data to include license references, and ensures license relationships are efficiently loaded from the database. The changes also include new integration tests to verify license functionality.

Licenses API and Model Integration

Added new API endpoints and implementation for listing and retrieving licenses, including associated license rules, via LicensesApiImpl and OpenAPI generator files. [1] [2] [3] [4] [5]
Updated the database population script to insert licenses and license-rule associations from test data, ensuring feeds can reference licenses and rules. [1] [2]

Feed Model and Query Enhancements

Modified feed queries to efficiently join and load license relationships, preventing N+1 query issues and making license info available for model conversion. [1] [2] [3]
Updated BasicFeedImpl.from_orm to expose license fields (license_id, license_is_spdx, license_notes) in API responses. [1] [2]
Adjusted feed population logic to set license_id and license_notes from test data, handling missing/empty values gracefully.

Testing and Documentation

Added integration and unit tests for license endpoints and feed license fields, verifying correct API behavior and data relationships. [1] [2] [3]
Extended OpenAPI documentation and test data to cover license entities and their associations. [1] [2] [3] [4] [5]

Testing tips:

On top of the random queries listed below, added some integration tests.

Provide tips, procedures and sample files on how to test the feature.
Testers are invited to follow the tips AND to try anything they deem relevant outside the bounds of the testing tips.

Please make sure these boxes are checked before submitting your pull request - thanks!

Run the unit tests with ./scripts/api-tests.sh to make sure you didn't break anything
Add or update any needed documentation to the repo
Format the title like "feat: [new feature short description]". Title must follow the Conventional Commit Specification(https://www.conventionalcommits.org/en/v1.0.0/).
Linked all relevant issues
Include screenshot(s) showing how this pull request works and fixes the issue(s)

jcpitre · 2025-11-25T18:57:27Z

Here is an example of the /v1/feeds/{id} call:

curl -X 'GET' 'http://localhost:8080/v1/feeds/mdb-1172' -H 'accept: application/json'
{
  "id": "mdb-1172",
  "data_type": "gtfs",
  "created_at": "2024-02-08T00:00:00Z",
  "external_ids": [
    {
      "external_id": "1172",
      "source": "mdb"
    }
  ],
  "provider": "Verkehrsverbund Mittelthüringen (VMT)",
  "feed_contact_email": "[email protected]",
  "source_info": {
    "producer_url": "https://www.vmt-thueringen.de/fileadmin/VMT_Redaktion/OPEN_DATA/VMT_GTFS.zip",
    "authentication_type": 0,
    "authentication_info_url": "",
    "api_key_parameter_name": "",
    "license_url": "https://creativecommons.org/licenses/by-nd/2.0/de/",
    "license_id": "CC-BY-ND-2.0",
    "license_is_spdx": true,
    "license_notes": "Detected locale/jurisdiction port 'de'. SPDX does not list ported CC licenses; using canonical ID."
  },
  "redirects": [],
  "status": "future",
  "official": true,
  "official_updated_at": "2025-01-22T20:19:42.509622",
  "feed_name": "",
  "note": "",
  "related_links": []
}

And for the /v1/licenses/{id} call (Updated after commit 1b21765)

curl -X 'GET' 'http://localhost:8080/v1/licenses/CC-BY-4.0' -H 'accept: application/json'
{
  "id": "CC-BY-4.0",
  "type": "standard",
  "is_spdx": true,
  "name": "Creative Commons Attribution 4.0 International",
  "url": "https://creativecommons.org/licenses/by/4.0/legalcode",
  "description": null,
  "created_at": "2025-11-19T21:57:02.519627",
  "updated_at": "2025-11-19T21:57:02.519685",
  "license_rules": [
    {
      "name": "commercial-use",
      "label": "Commercial use",
      "description": "This license allows the software or data to be used for commercial purposes.",
      "type": "permission"
    },
    {
      "name": "modifications",
      "label": "Modification",
      "description": "This license allows the software or content to be modified.",
      "type": "permission"
    },
    {
      "name": "distribution",
      "label": "Distribution",
      "description": "This license allows the software or content to be redistributed.",
      "type": "permission"
    },
    {
      "name": "private-use",
      "label": "Private use",
      "description": "This license allows private use and modification.",
      "type": "permission"
    },
    {
      "name": "patent-use",
      "label": "Patent use",
      "description": "This license includes an express grant of patent rights from contributors.",
      "type": "permission"
    },
    {
      "name": "include-copyright",
      "label": "Include copyright",
      "description": "A copy of the license and copyright notice must be included.",
      "type": "condition"
    },
    {
      "name": "document-changes",
      "label": "Document changes",
      "description": "Changes made must be clearly documented.",
      "type": "condition"
    },
    {
      "name": "trademark-use",
      "label": "Trademark use",
      "description": "The license does not grant rights to use trademarks.",
      "type": "limitation"
    },
    {
      "name": "liability",
      "label": "Liability disclaimer",
      "description": "The license includes a limitation of liability.",
      "type": "limitation"
    },
    {
      "name": "warranty",
      "label": "No warranty",
      "description": "The license explicitly states that no warranty is provided.",
      "type": "limitation"
    }
  ]
}

jcpitre · 2025-11-25T19:05:01Z

Example of /v1/licenses (Updated after commit 1b21765)

curl -X 'GET' 'http://localhost:8080/v1/licenses?limit=2' -H 'accept: application/json'
[
  {
    "id": "0BSD",
    "type": "standard",
    "is_spdx": true,
    "name": "BSD Zero Clause License",
    "url": "https://opensource.org/licenses/0BSD",
    "description": null,
    "created_at": "2025-11-19T21:57:02.217375",
    "updated_at": "2025-11-19T21:57:02.217486"
  },
  {
    "id": "3D-Slicer-1.0",
    "type": "standard",
    "is_spdx": true,
    "name": "3D Slicer License v1.0",
    "url": "https://github.com/Slicer/Slicer/blob/main/License.txt",
    "description": null,
    "created_at": "2025-11-19T21:57:02.223643",
    "updated_at": "2025-11-19T21:57:02.223726"
  }
]
``1
Note that license_rules is not present when getting a list of licenses.

emmambd · 2025-11-25T20:02:18Z

Wonder what purpose license_notes serves and why it's in the feeds endpoint but not the license ones?

github-actions · 2025-11-25T21:06:19Z

*Lighthouse ran on https://mobility-feeds-dev--pr-1482-e7wegjpi.web.app/ * (Desktop)
⚡️ HTML Report Lighthouse report for the changes in this PR:

Performance	Accessibility	Best Practices	SEO
🟠 78	🟢 100	🟢 100	🟢 100

*Lighthouse ran on https://mobility-feeds-dev--pr-1482-e7wegjpi.web.app/feeds * (Desktop)
⚡️ HTML Report Lighthouse report for the changes in this PR:

Performance	Accessibility	Best Practices	SEO
🟠 86	🟢 91	🟢 100	🟢 100

*Lighthouse ran on https://mobility-feeds-dev--pr-1482-e7wegjpi.web.app/feeds/gtfs/mdb-2126 * (Desktop)
⚡️ HTML Report Lighthouse report for the changes in this PR:

Performance	Accessibility	Best Practices	SEO
🟠 74	🔴 0	🟢 93	🟢 100

*Lighthouse ran on https://mobility-feeds-dev--pr-1482-e7wegjpi.web.app/feeds/gtfs_rt/mdb-2585 * (Desktop)
⚡️ HTML Report Lighthouse report for the changes in this PR:

Performance	Accessibility	Best Practices	SEO
🟢 91	🟠 87	🟢 100	🟢 100

*Lighthouse ran on https://mobility-feeds-dev--pr-1482-e7wegjpi.web.app/gbfs/gbfs-flamingo_porirua * (Desktop)
⚡️ HTML Report Lighthouse report for the changes in this PR:

Performance	Accessibility	Best Practices	SEO
🟢 100	🟢 100	🟢 100	🟢 100

github-actions · 2025-11-25T21:06:30Z

Preview Firebase Hosting URL: https://mobility-feeds-dev--pr-1482-e7wegjpi.web.app

jcpitre · 2025-11-26T14:14:33Z

Wonder what purpose license_notes serves and why it's in the feeds endpoint but not the license ones?

@emmambd this just reflects the data in the database. I guess the license_notes are specific to the feed, maybe adding info on how the license was obtained, or how it applies to that feed?

davidgamez · 2025-11-26T14:33:56Z

.github/workflows/typescript-generator-gbfs-validator-types-check.yml

@@ -0,0 +1,56 @@
+name: Verify TypeScript GBFS Validator Types Generation


Thanks to @Alessandro100

davidgamez · 2025-11-26T14:35:55Z

api/src/feeds/impl/licenses_api_impl.py

+            lic_dict = {
+                "id": lic.id,
+                "type": lic.type,
+                "is_spdx": lic.is_spdx,
+                "name": lic.name,
+                "url": lic.url,
+                "description": lic.description,
+                "license_rules": [r.name for r in getattr(lic, "rules", [])],
+                "created_at": lic.created_at,
+                "updated_at": lic.updated_at,
+            }


Add this to the models folder, and it will avoid repetition

Added license_base_impl.py and license_with_rules_impl.py

davidgamez · 2025-11-26T14:44:35Z

api/src/shared/db_models/basic_feed_impl.py

+        # Determine license_is_spdx from the related License ORM if available
+        license_is_spdx = None
+        try:
+            if getattr(feed, "license", None) is not None:
+                license_is_spdx = feed.license.is_spdx
+        except Exception:
+            # be conservative and keep None if anything goes wrong
+            license_is_spdx = None


We can skip the try/except clause here.

Suggested change

# Determine license_is_spdx from the related License ORM if available

license_is_spdx = None

try:

if getattr(feed, "license", None) is not None:

license_is_spdx = feed.license.is_spdx

except Exception:

# be conservative and keep None if anything goes wrong

license_is_spdx = None

# Determine license_is_spdx from the related License ORM if available

license_is_spdx = None

if getattr(feed, "license", None) is not None:

license_is_spdx = feed.license.is_spdx

davidgamez · 2025-11-26T14:46:39Z

docs/DatabaseCatalogAPI.yaml

+          type: boolean
+          example: true
+        license_notes:
+          description: TBD


This is a generic text notes field. We can document it with:

Suggested change

description: TBD

description: Notes associated with the feed license.

davidgamez · 2025-11-26T14:51:19Z

docs/DatabaseCatalogAPI.yaml

+          example: 0BSD
+        type:
+          type: string
+          description: TBD


Let's connect to go over all pending TBD documention

Removed all TBD values and put something that seemed correct.

davidgamez · 2025-11-26T14:53:20Z

api/src/feeds/impl/licenses_api_impl.py

+                "name": lic.name,
+                "url": lic.url,
+                "description": lic.description,
+                "license_rules": [r.name for r in getattr(lic, "rules", [])],


[suggestion]: We can expose here the name and the label of each rule.

davidgamez · 2025-12-01T17:06:47Z

api/src/shared/db_models/license_with_rules_impl.py

+
+        return cls(
+            **base_license.model_dump(),
+            license_rules=rules or None,


[suggestion]: return an empty array instead of none, it's safer to parse on the consumer side.

Not sure about this one. The function is not supposed to return a list.

Sorry for the confussion, I'm talking about the license_rules

davidgamez

LGTM!

qcdyx and others added 6 commits November 19, 2025 08:36

added license info in get_feed

f7901b2

updated DatabaseCatalogAPI

9185164

Merge branch 'main' into 1345-add-license-information-to-the-api

dcf6b6c

Merge branch 'main' into 1345-add-license-information-to-the-api

c996d18

updated endpoints

01fad67

Added license API endpoint + feed license info

a66420b

jcpitre linked an issue Nov 25, 2025 that may be closed by this pull request

Add license information to the API #1345

Closed

Merge branch 'main' into 1345-add-license-information-to-the-api

a22871f

jcpitre marked this pull request as draft November 25, 2025 18:24

jcpitre changed the title ~~1345 add license information to the api~~ feat: add license information to the api Nov 25, 2025

jcpitre marked this pull request as ready for review November 25, 2025 20:00

jcpitre added 2 commits November 25, 2025 15:54

Changed types.ts. Adjusted limit for the licenses endpoint.

5857354

Removed an extra file committed by error.

da92b34

gbfs types github action separation

2b98e07

davidgamez reviewed Nov 26, 2025

View reviewed changes

jcpitre added 3 commits November 27, 2025 21:57

Merge branch 'main' into 1345-add-license-information-to-the-api

e91a2f9

Modified licenses endpoint to return all data in rules.

1b21765

Corrected the unit tests.

fc1ae95

davidgamez reviewed Dec 1, 2025

View reviewed changes

jcpitre added 2 commits December 1, 2025 21:24

Returned [] of there are no rules.

afdb6a1

Updated types.ts

26f8591

jcpitre requested a review from davidgamez December 2, 2025 02:58

davidgamez approved these changes Dec 2, 2025

View reviewed changes

davidgamez merged commit 57525b1 into main Dec 2, 2025
7 checks passed

davidgamez deleted the 1345-add-license-information-to-the-api branch December 2, 2025 14:05

davidgamez mentioned this pull request Dec 2, 2025

feat: add license information to operations API #1506

Merged

5 tasks

		@@ -0,0 +1,56 @@
		name: Verify TypeScript GBFS Validator Types Generation

	description: TBD
	description: Notes associated with the feed license.

feat: add license information to the api #1482

feat: add license information to the api #1482

Uh oh!

Conversation

jcpitre commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jcpitre commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jcpitre commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

emmambd commented Nov 25, 2025

Uh oh!

github-actions bot commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Nov 25, 2025

Uh oh!

jcpitre commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidgamez left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

jcpitre commented Nov 25, 2025 •

edited

Loading

jcpitre commented Nov 25, 2025 •

edited

Loading

jcpitre commented Nov 25, 2025 •

edited

Loading

github-actions bot commented Nov 25, 2025 •

edited

Loading

jcpitre commented Nov 26, 2025 •

edited

Loading