search

marshmallow-code / marshmallow

A lightweight library for converting complex objects to and from simple Python datatypes.
https://marshmallow.readthedocs.io/
MIT License
7.04k stars 629 forks source link

There is no "description" or otherwise helpful attribute of a field #641

Closed stringfellow closed 7 years ago

stringfellow commented 7 years ago

Fields typically have some helpful text for a UI (be that graphical or command line) and it is surprising that marshmallow omits this.

While it is possible to casually add arbitrary properties to a field definition, it seems that encouraging users to follow some standard might be a good idea.

JSON Schema identifies "description" as a property to do this: http://json-schema.org/latest/json-schema-validation.html#rfc.section.7.2

and, marshmallow-jsonschema implements this too: https://github.com/fuhrysteve/marshmallow-jsonschema https://github.com/fuhrysteve/marshmallow-jsonschema/blob/master/marshmallow_jsonschema/base.py#L139

Could this be included?

netrounds-joakim commented 7 years ago

I agree with this, was just about to add such an issue myself.

A perfect use case for this is using https://github.com/rochacbruno/flasgger together with Flask to generate a REST API Swagger schema. They support Marshmallow, but when using that there is no way to describe what a field does, just its type.

sloria commented 7 years ago

I would rather not dictate how to store descriptions in marshmallow core. Descriptions are metadata that don't affect behavior, and there's already a way to store and access metadata:

field = fields.Field(description='A fine field.')
field.metadata['description']  # 'A fine field.'

This flexibility allows client libraries to use whatever name is appropriate (e.g. "description", "help", "desc", "info").