Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add minimal enum descriptions #837

Closed

Conversation

turbomam
Copy link
Member

@turbomam turbomam commented Aug 13, 2024

The LinkML linter (which we should all be using on a regular basis) expects enumerations to have descriptions, like all other schema elements. This PR adds descriptions that add some context without just repeating the name of the enums with different casing/punctuation for easier reading.

These enum descriptions can be improve over time. Note that the pattern used here (a count and naming of the slots that use the enum) is somewhat redundant in any system that pre-induced the slots.

The code that generated these enum descriptions will also highlight any enums that are not used by any slots, because they could be considered for deletion. There aren't any enums in that state right now.

So one results of this PR is that future linter results will be terser and thus it will be easier to see cases in which a term isn't complete by the default LinkML guidelines.

@turbomam turbomam linked an issue Aug 13, 2024 that may be closed by this pull request
@turbomam
Copy link
Member Author

turbomam commented Aug 13, 2024

The change in mixs.yaml is too large to see.

example:

MoldVisibilityEnum:
    name: MoldVisibilityEnum
    description: 'permissible values, used by 5 terms: ceil_water_mold, door_water_mold,
      shad_dev_water_mold, wall_water_mold, window_water_mold'
    from_schema: https://w3id.org/mixs
    permissible_values:
      no presence of mold visible:
        text: no presence of mold visible
      presence of mold visible:
        text: presence of mold visible

@turbomam
Copy link
Member Author

I think we should add the document divider --- to the beginning of src/mixs/schema/deprecated.yaml, as suggested by [Unchanged files with check annotations](Unchanged files with check annotations)

We could double check with Sierra, or learn more about where that warning is coming from.

@turbomam
Copy link
Member Author

turbomam commented Aug 13, 2024

Future action: convert these enums and all of the schema to terser forms like

MoldVisibilityEnum:
    description: 'permissible values, used by 5 terms: ceil_water_mold, door_water_mold,
      shad_dev_water_mold, wall_water_mold, window_water_mold'
    permissible_values:
      no presence of mold visible:
      presence of mold visible: {}
  • remove redundant name and text keys
  • remove from_schema from auto-generation

@mslarae13
Copy link
Contributor

I did a quick check, and the additions to mixs.yaml looks good..

I think we should add the document divider --- to the beginning of src/mixs/schema/deprecated.yaml, as suggested by [Unchanged files with check annotations](Unchanged files with check annotations)

We could double check with Sierra, or learn more about where that warning is coming from.

I am good with that. But should do it in a separate PR & issue. As this one is specifically enum descriptions & that change is totally unrelated. Too much in 1 PR

Future action: convert these enums and all of the schema to terser forms like

MoldVisibilityEnum:
    description: 'permissible values, used by 5 terms: ceil_water_mold, door_water_mold,
      shad_dev_water_mold, wall_water_mold, window_water_mold'
    permissible_values:
      no presence of mold visible:
      presence of mold visible: {}
  • remove redundant name and text keys
  • remove from_schema from auto-generation

Good idea, @turbomam . Can we merge this in and make a separate issue for this?

@mslarae13 mslarae13 self-requested a review September 19, 2024 15:36
@turbomam
Copy link
Member Author

turbomam commented Sep 23, 2024

Thanks @mslarae13

Terse dictionaries:

The document separator is now addressed in

I will also check out the apparent conflict in mixs.yaml

@turbomam
Copy link
Member Author

The conflict is due to the fact that we have some permissible values with texts now and some without

In the spirit of

I am going to remove the texts where they are conflict now

@turbomam turbomam changed the title with enum descriptions add minimal enum descriptions Sep 24, 2024
@turbomam
Copy link
Member Author

turbomam commented Oct 1, 2024

Sierra points out that the list of using slots would need to be maintained (which could be done by rerunning src/mixs/schema/mixs.yaml, which generates an all-inclusive YAML file)

should be part of Makefile

There are probably ~ 100 enumerations. Ideally we would add meaningful descriptions, like their provenance.

@turbomam
Copy link
Member Author

turbomam commented Oct 4, 2024

the code to regenerate this is now in

@turbomam
Copy link
Member Author

turbomam commented Oct 4, 2024

the output of the description process can now be found as assets/mixs-schema-formatting-variants/mixs_with_enum_descriptions.yaml

in

@turbomam
Copy link
Member Author

now redundant with

@turbomam turbomam closed this Oct 14, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.

Give enumerations boilerplate definitions for now
3 participants