starred/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2026-01-11 21:10:29 +01:00
Code Issues 273 Packages Projects Releases 10 Wiki Activity

GraphQL attribute types are inconsistent and documentation is incorrect #7497

New Issue
Closed
opened 2025-12-29 20:24:14 +01:00 by adam · 16 comments
adam commented 2025-12-29 20:24:14 +01:00
Owner
Copy Link

Originally created by @4xoc on GitHub (Jan 12, 2023).

Originally assigned to: @arthanson on GitHub.

NetBox version

v3.4.2

Python version

3.10

Steps to Reproduce

This issue ticket covers two problems going hand in hand. First is the incorrect schema documentation in GraphiQL, the other is incorrect use of types (always string for nummeric values)

Incorrect docs:

  1. Use GraphiQL to look into schemas for queries and attributes returned. Everything is a string except a few bools

Incorrect use of types:

  1. query for any object with id

Type missmatch between docs and reality:

  1. query for interface_list with mtu attribute. It is described as string type but int is returned.

Expected Behavior

  1. The Schema in GraphiQL represents the correct attribute type identical to the REST API.

  2. Nummerical values are returned as numbers in the response just like with the REST API.

  3. The Schema in GraphiQL actually describes attributes in the correct type they are being returned in.

Observed Behavior

  1. Schema always uses strings for all non-boolean attributes even though many attributes are clearly numbers (like ids).

  2. Many attributes that could be represented as numbers are strings like ids.

  3. Some attributes actually return ints like mtu on interfaces when docs say it's a string.

Originally created by @4xoc on GitHub (Jan 12, 2023). Originally assigned to: @arthanson on GitHub. ### NetBox version v3.4.2 ### Python version 3.10 ### Steps to Reproduce This issue ticket covers two problems going hand in hand. First is the incorrect schema documentation in GraphiQL, the other is incorrect use of types (always string for nummeric values) Incorrect docs: 1. Use GraphiQL to look into schemas for queries and attributes returned. Everything is a string except a few bools Incorrect use of types: 1. query for any object with id Type missmatch between docs and reality: 1. query for interface_list with mtu attribute. It is described as string type but int is returned. ### Expected Behavior 1. The Schema in GraphiQL represents the correct attribute type identical to the REST API. 2. Nummerical values are returned as numbers in the response just like with the REST API. 3. The Schema in GraphiQL actually describes attributes in the correct type they are being returned in. ### Observed Behavior 1. Schema always uses strings for all non-boolean attributes even though many attributes are clearly numbers (like ids). 2. Many attributes that could be represented as numbers are strings like ids. 3. Some attributes actually return ints like mtu on interfaces when docs say it's a string.
adam closed this issue 2025-12-29 20:24:14 +01:00
adam commented 2025-12-29 20:24:14 +01:00
Author
Owner
Copy Link

@ryanmerolle commented on GitHub (Feb 25, 2023):

@4xoc great issue! Would you be able to tackle this?

@ryanmerolle commented on GitHub (Feb 25, 2023): @4xoc great issue! Would you be able to tackle this?
adam commented 2025-12-29 20:24:15 +01:00
Author
Owner
Copy Link

@4xoc commented on GitHub (Feb 27, 2023):

I'm afraid my knowledge of Python and Django is close to nothing. From looking at things I would suspect this being the main cause. IDs are generally uint64 which may not be part of NumberFilter and thus cause the fallback to string. But this is nothing more than a guess. Not sure how that would explain differences between the docs and the actual returned type though.

@4xoc commented on GitHub (Feb 27, 2023): I'm afraid my knowledge of Python and Django is close to nothing. From looking at things I would suspect [this](https://github.com/netbox-community/netbox/blob/develop/netbox/netbox/graphql/utils.py#L5) being the main cause. IDs are generally uint64 which may not be part of `NumberFilter` and thus cause the fallback to string. But this is nothing more than a guess. Not sure how that would explain differences between the docs and the actual returned type though.
adam commented 2025-12-29 20:24:15 +01:00
Author
Owner
Copy Link

@4xoc commented on GitHub (Feb 27, 2023):

Apparently GraphQL doesn't support uint64 by default. One can create a custom scalar which should work for such cases.

@4xoc commented on GitHub (Feb 27, 2023): Apparently GraphQL doesn't support uint64 by default. One can create a [custom scalar](https://docs.graphene-python.org/en/latest/types/scalars/#custom-scalars) which should work for such cases.
adam commented 2025-12-29 20:24:15 +01:00
Author
Owner
Copy Link

@rmanyari commented on GitHub (Mar 1, 2023):

Happy to take a look at this, that being said, this is part of the public facing API and changes to types would imply breaking backwards compatibility (perhaps it will need a minor or even major release?)

I'm new to the project and would love the input from one of the more tenured members or maintainers.

  • How do we typically approach these types of changes and what type of backwards compatibility guarantees we offer to users?
  • Is there appetite for this type of changes ATM?
  • From what I've seen so far the UI only uses the REST API, so this wouldn't involve UI changes, can someone confirm?

Thanks!

@rmanyari commented on GitHub (Mar 1, 2023): Happy to take a look at this, that being said, this is part of the public facing API and changes to types would imply breaking backwards compatibility (perhaps it will need a minor or even major release?) I'm new to the project and would love the input from one of the more tenured members or maintainers. * How do we typically approach these types of changes and what type of backwards compatibility guarantees we offer to users? * Is there appetite for this type of changes ATM? * From what I've seen so far the UI only uses the REST API, so this wouldn't involve UI changes, can someone confirm? Thanks!
adam commented 2025-12-29 20:24:16 +01:00
Author
Owner
Copy Link

@arthanson commented on GitHub (Mar 22, 2023):

@4xoc I'm not sure I'm seeing this behavior, I do the following query for introspection:

{
  __type(name: "InterfaceType") {
    name
    fields {
      name
      type {
        name
        kind
      }
    }
  }
}

and get back for the mtu field:

        {
          "name": "mtu",
          "type": {
            "name": "Int",
            "kind": "SCALAR"
          }
        },

Can you post a query you use and the return (wrong) values?

@arthanson commented on GitHub (Mar 22, 2023): @4xoc I'm not sure I'm seeing this behavior, I do the following query for introspection: ``` { __type(name: "InterfaceType") { name fields { name type { name kind } } } } ``` and get back for the mtu field: ``` { "name": "mtu", "type": { "name": "Int", "kind": "SCALAR" } }, ``` Can you post a query you use and the return (wrong) values?
adam commented 2025-12-29 20:24:16 +01:00
Author
Owner
Copy Link

@4xoc commented on GitHub (Mar 27, 2023):

Yeah I looked at interface_list definition and arguments of it where MTU must be string. An interface object itself returns int correctly. To rephrase point no 3 from observed behavior: filter arguments that are int in the actual object are required to be string. In my mind id being a string is the biggest issue here.

@4xoc commented on GitHub (Mar 27, 2023): Yeah I looked at interface_list definition and arguments of it where MTU must be string. An interface object itself returns int correctly. To rephrase point no 3 from observed behavior: filter arguments that are int in the actual object are required to be string. In my mind id being a string is the biggest issue here.
adam commented 2025-12-29 20:24:16 +01:00
Author
Owner
Copy Link

@bluikko commented on GitHub (Apr 7, 2023):

I also was wondering about this when starting to move from REST to GraphQL. I believe this issue refers to example like this:
image
Is this the correct example? Note how all the IDs are of type "String" - in fact almost everything is "String" except some Booleans.

@bluikko commented on GitHub (Apr 7, 2023): I also was wondering about this when starting to move from REST to GraphQL. I believe this issue refers to example like this: ![image](https://user-images.githubusercontent.com/14869000/230541659-785e038a-122a-4b0b-982a-cbc97fafdfc1.png) Is this the correct example? Note how all the IDs are of type "String" - in fact almost everything is "String" except some Booleans.
adam commented 2025-12-29 20:24:16 +01:00
Author
Owner
Copy Link

@4xoc commented on GitHub (Apr 10, 2023):

Is this the correct example? Note how all the IDs are of type "String" - in fact almost everything is "String" except some Booleans.

That's exactly it. I believe to have seen some other cases in but can't find any example so I may confuse this again with query parameters (which is probably worth fixing as well).

@4xoc commented on GitHub (Apr 10, 2023): > Is this the correct example? Note how all the IDs are of type "String" - in fact almost everything is "String" except some Booleans. That's exactly it. I believe to have seen some other cases in but can't find any example so I may confuse this again with query parameters (which is probably worth fixing as well).
adam commented 2025-12-29 20:24:16 +01:00
Author
Owner
Copy Link

@arthanson commented on GitHub (Aug 7, 2023):

I'm not sure this is a bug, the above screenshot looks like it is from the GraphiQL browser schema pane which shows things like id as "id: [String]" but if you look at the actual schema definition yaml file it is type array of integers, which the GraphiQL is unhelpfully showing as String. From the yaml file:

      - in: query
        name: id
        schema:
          type: array
          items:
            type: integer
            format: int32
        explode: true
        style: form

That does look correct.

@arthanson commented on GitHub (Aug 7, 2023): I'm not sure this is a bug, the above screenshot looks like it is from the GraphiQL browser schema pane which shows things like id as "id: [String]" but if you look at the actual schema definition yaml file it is type array of integers, which the GraphiQL is unhelpfully showing as String. From the yaml file: ``` - in: query name: id schema: type: array items: type: integer format: int32 explode: true style: form ``` That does look correct.
adam commented 2025-12-29 20:24:16 +01:00
Author
Owner
Copy Link

@4xoc commented on GitHub (Aug 7, 2023):

The result from graphql certainly is a string and is required to be a string for queries too. I believe that int32 is incorrect too, some time ago all IDs got changed to int64. IDs definitely are represented as strings.

image

@4xoc commented on GitHub (Aug 7, 2023): The result from graphql certainly is a string and is required to be a string for queries too. I believe that int32 is incorrect too, some time ago all IDs got changed to int64. IDs definitely are represented as strings. ![image](https://github.com/netbox-community/netbox/assets/12109998/366b850d-2d67-4b30-af70-4cc280d6407c)
adam commented 2025-12-29 20:24:17 +01:00
Author
Owner
Copy Link

@arthanson commented on GitHub (Aug 9, 2023):

Okay, makes sense - was getting a bit confused as I was talking about query params instead of the object itself. Probably using type ID (https://graphql.org/learn/schema/#scalar-types) would be the most correct:

"ID: The ID scalar type represents a unique identifier, often used to refetch an object or as the key for a cache. The ID type is serialized in the same way as a String; however, defining it as an ID signifies that it is not intended to be human‐readable."

@arthanson commented on GitHub (Aug 9, 2023): Okay, makes sense - was getting a bit confused as I was talking about query params instead of the object itself. Probably using type ID (https://graphql.org/learn/schema/#scalar-types) would be the most correct: "ID: The ID scalar type represents a unique identifier, often used to refetch an object or as the key for a cache. The ID type is serialized in the same way as a String; however, defining it as an ID signifies that it is not intended to be human‐readable."
adam commented 2025-12-29 20:24:17 +01:00
Author
Owner
Copy Link

@arthanson commented on GitHub (Oct 10, 2023):

As stated above GraphQL doesn't natively support int64 but you can use scalars, when we move to strawberry #9856 we can replace it with https://strawberry.rocks/docs/types/scalars#int64 marking as blocked by #9856

@arthanson commented on GitHub (Oct 10, 2023): As stated above GraphQL doesn't natively support int64 but you can use scalars, when we move to strawberry #9856 we can replace it with https://strawberry.rocks/docs/types/scalars#int64 marking as blocked by #9856
adam commented 2025-12-29 20:24:17 +01:00
Author
Owner
Copy Link

@arthanson commented on GitHub (May 20, 2024):

@4xoc I think this is resolved in NetBox 4.x as the new strawberry returns the fields as ID fields "The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID." Can you please confirm that this would resolve the issue for you.

@arthanson commented on GitHub (May 20, 2024): @4xoc I think this is resolved in NetBox 4.x as the new strawberry returns the fields as ID fields "The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID." Can you please confirm that this would resolve the issue for you.
adam commented 2025-12-29 20:24:17 +01:00
Author
Owner
Copy Link

@4xoc commented on GitHub (May 29, 2024):

I've not yet had a chance to look into a 4.x installation but looking through the documentation it appears as using ID type scalar solves the issue of supplying integers for queries.

However, on the return side of things it'll still return a string that has to be parsed client side. Looking at the docs it looks to me like maybe using BigInt (https://strawberry.rocks/docs/types/scalars#bigint-64-bit-integers) would be a better way to go. Afaik IDs in Netbox are unsigned 64 bit integers and thus should be returned as such. I don't think Python itself sees a difference as everything is just int so it probably works with bigint out of the box.

@4xoc commented on GitHub (May 29, 2024): I've not yet had a chance to look into a 4.x installation but looking through the documentation it appears as using ID type scalar solves the issue of supplying integers for queries. However, on the return side of things it'll still return a string that has to be parsed client side. Looking at the docs it looks to me like maybe using BigInt (https://strawberry.rocks/docs/types/scalars#bigint-64-bit-integers) would be a better way to go. Afaik IDs in Netbox are unsigned 64 bit integers and thus should be returned as such. I don't think Python itself sees a difference as everything is just int so it probably works with bigint out of the box.
adam commented 2025-12-29 20:24:17 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Jun 6, 2024):

This is a reminder that additional information is needed in order to further triage this issue. If the requested details are not provided, the issue will soon be closed automatically.

@github-actions[bot] commented on GitHub (Jun 6, 2024): This is a reminder that additional information is needed in order to further triage this issue. If the requested details are not provided, the issue will soon be closed automatically.
adam commented 2025-12-29 20:24:18 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Jun 14, 2024):

This issue is being closed as no further information has been provided. If you would like to revisit this topic, please first modify your original post to include all the requested detail, and then ask that the issue be reopened.

@github-actions[bot] commented on GitHub (Jun 14, 2024): This issue is being closed as no further information has been provided. If you would like to revisit this topic, please first modify your original post to include all the requested detail, and then ask that the issue be reopened.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
beta
breaking change
complexity: high
complexity: low
complexity: medium
needs milestone
netbox
pending closure
plugin candidate
pull-request
Mirrored from GitHub Pull Request
 severity: high
severity: low
severity: medium
status: accepted
status: backlog
status: blocked
status: duplicate
status: needs owner
status: needs triage
status: revisions needed
status: under review
topic: GraphQL
topic: Internationalization
topic: OpenAPI
topic: UI/UX
topic: cabling
topic: event rules
topic: htmx navigation
topic: industrialization
topic: migrations
topic: plugins
topic: scripts
topic: templating
topic: testing
type: bug
type: deprecation
type: documentation
type: feature
type: housekeeping
type: translation
No Label pending closure severity: low status: revisions needed topic: GraphQL type: bug
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/netbox#7497
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?